From 4829bb3a151c4b4e58580313784862eb966921e1 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Wed, 19 Aug 2026 21:25:06 -0700
Subject: [PATCH 01/35] fix(prompt_management): don't route requests without
 prompt_id to prompt managers that can't run them

UI-injected empty vector_store_ids/tags/guardrails on a DB model tripped the
dynamic-param check, and the prompt-management fallback then handed the request
to the first registered prompt manager (e.g. a saved dotprompt), whose sync
path raised "prompt_id is required" as a 500 on every /chat/completions call.

Empty dynamic params no longer count as a trigger, the fallback skips managers
whose should_run_prompt_management declines a None prompt_id, and the sync base
path returns the request unchanged for a None prompt_id like the async path.
---
 .../integrations/prompt_management_base.py    |  2 +-
 litellm/litellm_core_utils/litellm_logging.py | 30 ++++++-
 .../test_litellm_logging.py                   | 78 +++++++++++++++++++
 3 files changed, 105 insertions(+), 5 deletions(-)

diff --git a/litellm/integrations/prompt_management_base.py b/litellm/integrations/prompt_management_base.py
index d16afa92ec2..81c01599e77 100644
--- a/litellm/integrations/prompt_management_base.py
+++ b/litellm/integrations/prompt_management_base.py
@@ -165,7 +165,7 @@ class PromptManagementBase(ABC):
         ignore_prompt_manager_optional_params: bool | None = False,
     ) -> tuple[str, list[AllMessageValues], dict]:
         if prompt_id is None:
-            raise ValueError("prompt_id is required for Prompt Management Base class")
+            return model, messages, non_default_params
         if not self.should_run_prompt_management(
             prompt_id=prompt_id,
             prompt_spec=prompt_spec,
diff --git a/litellm/litellm_core_utils/litellm_logging.py b/litellm/litellm_core_utils/litellm_logging.py
index 91a312b4f45..9b7707eabe1 100644
--- a/litellm/litellm_core_utils/litellm_logging.py
+++ b/litellm/litellm_core_utils/litellm_logging.py
@@ -832,8 +832,8 @@ class Logging(LiteLLMLoggingBaseClass):
 
         eg. AnthropicCacheControlHook and BedrockKnowledgeBaseHook both don't require a `prompt_id` to be passed in, they are triggered by dynamic params
         """
-        for param in non_default_params:
-            if param in DynamicPromptManagementParamLiteral.list_all_params():
+        for param in DynamicPromptManagementParamLiteral.list_all_params():
+            if non_default_params.get(param):
                 return True
 
         #############################################################################
@@ -966,6 +966,23 @@ class Logging(LiteLLMLoggingBaseClass):
 
         return None
 
+    @staticmethod
+    def _prompt_manager_runs_without_prompt_id(
+        logger: CustomLogger,
+        prompt_spec: PromptSpec | None,
+        dynamic_callback_params: StandardCallbackDynamicParams | None,
+    ) -> bool:
+        if not isinstance(logger, CustomPromptManagement):
+            return False
+        try:
+            return logger.should_run_prompt_management(
+                prompt_id=None,
+                prompt_spec=prompt_spec,
+                dynamic_callback_params=dynamic_callback_params or StandardCallbackDynamicParams(),
+            )
+        except Exception:
+            return False
+
     def get_custom_logger_for_prompt_management(
         self,
         model: str,
@@ -1016,8 +1033,13 @@ class Logging(LiteLLMLoggingBaseClass):
             callback_type=CustomPromptManagement
         )
 
-        if prompt_management_loggers:
-            logger: Final = prompt_management_loggers[0]
+        for logger in prompt_management_loggers:
+            if prompt_id is None and not self._prompt_manager_runs_without_prompt_id(
+                logger=logger,
+                prompt_spec=prompt_spec,
+                dynamic_callback_params=dynamic_callback_params,
+            ):
+                continue
             self.model_call_details["prompt_integration"] = logger.__class__.__name__
             return logger
 
diff --git a/tests/test_litellm/litellm_core_utils/test_litellm_logging.py b/tests/test_litellm/litellm_core_utils/test_litellm_logging.py
index c2d73ea467d..05aa65034fb 100644
--- a/tests/test_litellm/litellm_core_utils/test_litellm_logging.py
+++ b/tests/test_litellm/litellm_core_utils/test_litellm_logging.py
@@ -5105,3 +5105,81 @@ def test_set_cost_breakdown_stores_vertex_location():
         cost_for_built_in_tools_cost_usd_dollar=0.0,
     )
     assert no_location.cost_breakdown.get("vertex_location") is None
+
+
+def test_prompt_hooks_skip_prompt_managers_when_no_prompt_id(logging_obj, tmp_path, monkeypatch):
+    """
+    Regression for UI-injected `vector_store_ids: []` and always-on non-empty `vector_store_ids`
+    with a registered prompt manager (e.g. dotprompt): requests without a prompt_id 500'd with
+    "prompt_id is required for Prompt Management Base class" instead of completing normally.
+    """
+    from litellm.integrations.dotprompt.dotprompt_manager import DotpromptManager
+    from litellm.integrations.vector_store_integrations.vector_store_pre_call_hook import (
+        VectorStorePreCallHook,
+    )
+    from litellm.types.vector_stores import LiteLLM_ManagedVectorStore
+    from litellm.vector_stores.vector_store_registry import VectorStoreRegistry
+
+    (tmp_path / "stem.prompt").write_text("---\nmodel: gemini-2.5-flash\n---\nyou are a stem tutor\n")
+    dotprompt_manager = DotpromptManager(prompt_directory=str(tmp_path))
+    litellm.logging_callback_manager.add_litellm_callback(dotprompt_manager)
+    monkeypatch.setattr(
+        litellm,
+        "vector_store_registry",
+        VectorStoreRegistry(
+            vector_stores=[LiteLLM_ManagedVectorStore(vector_store_id="vs_123", custom_llm_provider="openai")]
+        ),
+    )
+
+    messages = [{"role": "user", "content": "hi"}]
+    try:
+        assert not logging_obj.should_run_prompt_management_hooks(
+            prompt_id=None, non_default_params={"vector_store_ids": []}
+        )
+
+        assert logging_obj.get_chat_completion_prompt(
+            model="gemini-2.5-flash",
+            messages=messages,
+            non_default_params={"vector_store_ids": []},
+            prompt_variables=None,
+            prompt_id=None,
+        ) == ("gemini-2.5-flash", messages, {"vector_store_ids": []})
+
+        assert dotprompt_manager.get_chat_completion_prompt(
+            model="gemini-2.5-flash",
+            messages=messages,
+            non_default_params={},
+            prompt_id=None,
+            prompt_variables=None,
+            dynamic_callback_params={},
+        ) == ("gemini-2.5-flash", messages, {})
+
+        assert logging_obj.should_run_prompt_management_hooks(
+            prompt_id=None, non_default_params={"vector_store_ids": ["vs_123"]}
+        )
+        assert isinstance(
+            logging_obj.get_custom_logger_for_prompt_management(
+                model="gemini-2.5-flash",
+                non_default_params={"vector_store_ids": ["vs_123"]},
+                prompt_id=None,
+                dynamic_callback_params={},
+            ),
+            VectorStorePreCallHook,
+        )
+
+        assert isinstance(
+            logging_obj.get_custom_logger_for_prompt_management(
+                model="gemini-2.5-flash",
+                non_default_params={},
+                prompt_id="stem",
+                dynamic_callback_params={},
+            ),
+            DotpromptManager,
+        )
+    finally:
+        litellm.logging_callback_manager.remove_callback_from_list_by_object(litellm.callbacks, dotprompt_manager)
+        litellm.logging_callback_manager.remove_callback_from_list_by_object(
+            litellm._async_success_callback, dotprompt_manager
+        )
+        for hook in [cb for cb in litellm.callbacks if isinstance(cb, VectorStorePreCallHook)]:
+            litellm.logging_callback_manager.remove_callback_from_list_by_object(litellm.callbacks, hook)

From b780b1e23c160ee8b8eb3effe471c280547fa10f Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Wed, 19 Aug 2026 21:38:15 -0700
Subject: [PATCH 02/35] fix(arize): decline prompt management runs without a
 prompt_id

Arize Phoenix claimed it could run without a prompt_id while its compiler
requires one, so the no-prompt_id fallback could select it and fail instead
of reaching the vector-store hook. It now declines like the other managers.
---
 .../arize/arize_phoenix_prompt_manager.py        |  6 +++---
 .../litellm_core_utils/test_litellm_logging.py   | 16 ++++++++++++----
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/litellm/integrations/arize/arize_phoenix_prompt_manager.py b/litellm/integrations/arize/arize_phoenix_prompt_manager.py
index fa178a02752..71f4902bbe5 100644
--- a/litellm/integrations/arize/arize_phoenix_prompt_manager.py
+++ b/litellm/integrations/arize/arize_phoenix_prompt_manager.py
@@ -359,10 +359,10 @@ class ArizePhoenixPromptManager(CustomPromptManagement):
         """
         Determine if prompt management should run based on the prompt_id.
 
-        For Arize Phoenix, we always return True and handle the prompt loading
-        in the _compile_prompt_helper method.
+        Arize Phoenix needs a prompt_id to compile, so it declines requests without one;
+        prompt loading itself happens in the _compile_prompt_helper method.
         """
-        return True
+        return prompt_id is not None
 
     def _compile_prompt_helper(
         self,
diff --git a/tests/test_litellm/litellm_core_utils/test_litellm_logging.py b/tests/test_litellm/litellm_core_utils/test_litellm_logging.py
index 05aa65034fb..db64340f895 100644
--- a/tests/test_litellm/litellm_core_utils/test_litellm_logging.py
+++ b/tests/test_litellm/litellm_core_utils/test_litellm_logging.py
@@ -5113,6 +5113,7 @@ def test_prompt_hooks_skip_prompt_managers_when_no_prompt_id(logging_obj, tmp_pa
     with a registered prompt manager (e.g. dotprompt): requests without a prompt_id 500'd with
     "prompt_id is required for Prompt Management Base class" instead of completing normally.
     """
+    from litellm.integrations.arize.arize_phoenix_prompt_manager import ArizePhoenixPromptManager
     from litellm.integrations.dotprompt.dotprompt_manager import DotpromptManager
     from litellm.integrations.vector_store_integrations.vector_store_pre_call_hook import (
         VectorStorePreCallHook,
@@ -5122,7 +5123,9 @@ def test_prompt_hooks_skip_prompt_managers_when_no_prompt_id(logging_obj, tmp_pa
 
     (tmp_path / "stem.prompt").write_text("---\nmodel: gemini-2.5-flash\n---\nyou are a stem tutor\n")
     dotprompt_manager = DotpromptManager(prompt_directory=str(tmp_path))
+    arize_manager = ArizePhoenixPromptManager(api_key="fake-key", api_base="http://127.0.0.1:9")
     litellm.logging_callback_manager.add_litellm_callback(dotprompt_manager)
+    litellm.logging_callback_manager.add_litellm_callback(arize_manager)
     monkeypatch.setattr(
         litellm,
         "vector_store_registry",
@@ -5154,6 +5157,10 @@ def test_prompt_hooks_skip_prompt_managers_when_no_prompt_id(logging_obj, tmp_pa
             dynamic_callback_params={},
         ) == ("gemini-2.5-flash", messages, {})
 
+        assert not arize_manager.should_run_prompt_management(
+            prompt_id=None, prompt_spec=None, dynamic_callback_params={}
+        )
+
         assert logging_obj.should_run_prompt_management_hooks(
             prompt_id=None, non_default_params={"vector_store_ids": ["vs_123"]}
         )
@@ -5177,9 +5184,10 @@ def test_prompt_hooks_skip_prompt_managers_when_no_prompt_id(logging_obj, tmp_pa
             DotpromptManager,
         )
     finally:
-        litellm.logging_callback_manager.remove_callback_from_list_by_object(litellm.callbacks, dotprompt_manager)
-        litellm.logging_callback_manager.remove_callback_from_list_by_object(
-            litellm._async_success_callback, dotprompt_manager
-        )
+        for manager in (dotprompt_manager, arize_manager):
+            litellm.logging_callback_manager.remove_callback_from_list_by_object(litellm.callbacks, manager)
+            litellm.logging_callback_manager.remove_callback_from_list_by_object(
+                litellm._async_success_callback, manager
+            )
         for hook in [cb for cb in litellm.callbacks if isinstance(cb, VectorStorePreCallHook)]:
             litellm.logging_callback_manager.remove_callback_from_list_by_object(litellm.callbacks, hook)

From 5c7604d7facd84df1767a8c2b65a3fb0cfb3873d Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Wed, 19 Aug 2026 23:05:30 -0700
Subject: [PATCH 03/35] test(prompt_management): cover
 _prompt_manager_runs_without_prompt_id directly

---
 .../test_litellm_logging.py                   | 28 +++++++++++++------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/tests/test_litellm/litellm_core_utils/test_litellm_logging.py b/tests/test_litellm/litellm_core_utils/test_litellm_logging.py
index db64340f895..82de634b488 100644
--- a/tests/test_litellm/litellm_core_utils/test_litellm_logging.py
+++ b/tests/test_litellm/litellm_core_utils/test_litellm_logging.py
@@ -5115,6 +5115,7 @@ def test_prompt_hooks_skip_prompt_managers_when_no_prompt_id(logging_obj, tmp_pa
     """
     from litellm.integrations.arize.arize_phoenix_prompt_manager import ArizePhoenixPromptManager
     from litellm.integrations.dotprompt.dotprompt_manager import DotpromptManager
+    from litellm.integrations.vector_store_integrations.base_vector_store import BaseVectorStore
     from litellm.integrations.vector_store_integrations.vector_store_pre_call_hook import (
         VectorStorePreCallHook,
     )
@@ -5164,14 +5165,25 @@ def test_prompt_hooks_skip_prompt_managers_when_no_prompt_id(logging_obj, tmp_pa
         assert logging_obj.should_run_prompt_management_hooks(
             prompt_id=None, non_default_params={"vector_store_ids": ["vs_123"]}
         )
-        assert isinstance(
-            logging_obj.get_custom_logger_for_prompt_management(
-                model="gemini-2.5-flash",
-                non_default_params={"vector_store_ids": ["vs_123"]},
-                prompt_id=None,
-                dynamic_callback_params={},
-            ),
-            VectorStorePreCallHook,
+        selected_logger = logging_obj.get_custom_logger_for_prompt_management(
+            model="gemini-2.5-flash",
+            non_default_params={"vector_store_ids": ["vs_123"]},
+            prompt_id=None,
+            dynamic_callback_params={},
+        )
+        assert isinstance(selected_logger, VectorStorePreCallHook)
+
+        assert logging_obj._prompt_manager_runs_without_prompt_id(
+            logger=BaseVectorStore(), prompt_spec=None, dynamic_callback_params=None
+        )
+        assert not logging_obj._prompt_manager_runs_without_prompt_id(
+            logger=selected_logger, prompt_spec=None, dynamic_callback_params=None
+        )
+        assert not logging_obj._prompt_manager_runs_without_prompt_id(
+            logger=dotprompt_manager, prompt_spec=None, dynamic_callback_params=None
+        )
+        assert not logging_obj._prompt_manager_runs_without_prompt_id(
+            logger=arize_manager, prompt_spec=None, dynamic_callback_params=None
         )
 
         assert isinstance(

From 021a09b1560d9bd79c5abc102d919aa9e18c867b Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 02:00:29 -0700
Subject: [PATCH 04/35] fix(passthrough): resolve vertex live credentials from
 db model deployments

The /vertex_ai/live WebSocket passthrough only ever looked at
default_vertex_config and the DEFAULT_VERTEXAI_* env vars, so a proxy whose
Vertex credentials live in the DB as a model entry with use_in_pass_through
had nothing to authenticate with. The upgrade still succeeded and the socket
then closed with a bare 1000 on the first client frame, which gave the client
no way to tell a misconfiguration from a normal end of session.

Credentials now also resolve from the router deployments flagged
use_in_pass_through, preferring the one matching the requested model, and a
failure to mint an access token closes 1011 with a reason naming both ways to
configure it. Upstream closes other than a plain 1000 are relayed to the client
with their code and reason, so Google's own errors reach the caller. The setup
frame's model is rewritten to the full projects/.../publishers/google/models
resource path, which is what Vertex expects and what lets a bare model id or a
gateway alias work over this route.
---
 litellm/constants.py                          |   3 +
 .../llm_passthrough_endpoints.py              | 152 ++++++++++---
 .../pass_through_endpoints.py                 |  75 ++++++-
 .../passthrough_endpoint_router.py            |  65 +++++-
 .../test_llm_pass_through_endpoints.py        | 101 +++++++++
 .../test_pass_through_endpoints.py            | 206 ++++++++++++++++++
 .../test_passthrough_endpoint_router.py       | 141 ++++++++++++
 7 files changed, 701 insertions(+), 42 deletions(-)

diff --git a/litellm/constants.py b/litellm/constants.py
index facfc6f7c19..3ce2cfd35a5 100644
--- a/litellm/constants.py
+++ b/litellm/constants.py
@@ -244,6 +244,9 @@ AIOHTTP_NEEDS_CLEANUP_CLOSED: Final = (3, 13, 0) <= sys.version_info < (
 _max_size_env: Final = os.getenv("REALTIME_WEBSOCKET_MAX_MESSAGE_SIZE_BYTES")
 REALTIME_WEBSOCKET_MAX_MESSAGE_SIZE_BYTES: Final = int(_max_size_env) if _max_size_env is not None else None
 
+# RFC 6455 caps the close frame payload at 125 bytes, 2 of which carry the status code
+WEBSOCKET_CLOSE_REASON_MAX_BYTES: Final = 123
+
 # SSL/TLS cipher configuration for faster handshakes
 # Strategy: Strongly prefer fast modern ciphers, but allow fallback to commonly supported ones
 # This balances performance with broad compatibility
diff --git a/litellm/proxy/pass_through_endpoints/llm_passthrough_endpoints.py b/litellm/proxy/pass_through_endpoints/llm_passthrough_endpoints.py
index c5ab7f1fc63..050ad0fd627 100644
--- a/litellm/proxy/pass_through_endpoints/llm_passthrough_endpoints.py
+++ b/litellm/proxy/pass_through_endpoints/llm_passthrough_endpoints.py
@@ -9,8 +9,9 @@ Use litellm with Anthropic SDK, Vertex AI SDK, Cohere SDK, etc.
 import json
 import os
 import re
+from collections.abc import Callable
 from types import MappingProxyType
-from typing import Annotated, Any, Final, cast
+from typing import TYPE_CHECKING, Annotated, Any, Final, cast
 
 import httpx
 from fastapi import APIRouter, Depends, HTTPException, Request, Response, WebSocket
@@ -55,11 +56,15 @@ from litellm.types.passthrough_endpoints.pass_through_endpoints import (
     LITELLM_PASS_THROUGH_CUSTOM_BODY_STATE_KEY,
     LITELLM_PASS_THROUGH_RAW_BODY_STATE_KEY,
 )
+from litellm.types.passthrough_endpoints.vertex_ai import VertexPassThroughCredentials
 from litellm.types.utils import LlmProviders
 from litellm.utils import ProviderConfigManager
 
 from .passthrough_endpoint_router import PassthroughEndpointRouter
 
+if TYPE_CHECKING:
+    from litellm.router import Router
+
 vertex_llm_base: Final = VertexBase()
 router: Final = APIRouter()
 openai_passthrough_router: Final = APIRouter()
@@ -2373,6 +2378,89 @@ async def cursor_proxy_route(
     return received_value
 
 
+VERTEX_LIVE_UNCONFIGURED_CLOSE_REASON: Final = (
+    "Vertex AI auth failed: set a use_in_pass_through vertex model, default_vertex_config, or DEFAULT_VERTEXAI_* env"
+)
+
+VERTEX_PUBLISHER_MODEL_PREFIX: Final = "publishers/google/models/"
+
+
+def _get_llm_router() -> "Router | None":
+    from litellm.proxy.proxy_server import llm_router
+
+    return llm_router
+
+
+def _resolve_vertex_live_credentials(
+    vertex_project: str | None,
+    vertex_location: str | None,
+    model: str | None,
+) -> VertexPassThroughCredentials | None:
+    """
+    Resolution order: credentials registered for the requested project/location, then any DB model entry
+    flagged ``use_in_pass_through``, then ``default_vertex_config`` and the ``DEFAULT_VERTEXAI_*`` env vars
+    """
+    keyed: Final = passthrough_endpoint_router.get_vertex_credentials(
+        project_id=vertex_project,
+        location=vertex_location,
+    )
+    if keyed is not None and keyed.vertex_project is not None:
+        return keyed
+    from_deployments: Final = passthrough_endpoint_router.get_vertex_credentials_from_router_deployments(model=model)
+    if from_deployments is not None:
+        return from_deployments
+    if keyed is not None:
+        return keyed
+    passthrough_endpoint_router.set_default_vertex_config()
+    return passthrough_endpoint_router.get_vertex_credentials(
+        project_id=vertex_project,
+        location=vertex_location,
+    )
+
+
+def _build_vertex_live_setup_model_rewriter(
+    vertex_project: str | None,
+    vertex_location: str | None,
+    llm_router: "Router | None",
+) -> Callable[[str], str] | None:
+    """
+    Rewrite the ``setup`` frame's model into the full Vertex resource path the Live API requires.
+
+    Clients address the gateway the way they address LiteLLM (bare id or model alias); Vertex reads anything
+    that is not a ``projects/...`` path as a project name and closes the socket
+    """
+    if vertex_project is None or vertex_location is None:
+        return None
+
+    def rewrite(setup_model: str) -> str:
+        if setup_model.startswith("projects/"):
+            return setup_model
+        aliased: Final = _resolve_alias_to_upstream_model(setup_model, llm_router)
+        return (
+            f"projects/{vertex_project}/locations/{vertex_location}/"
+            f"{VERTEX_PUBLISHER_MODEL_PREFIX}{aliased.removeprefix(VERTEX_PUBLISHER_MODEL_PREFIX)}"
+        )
+
+    return rewrite
+
+
+def _resolve_alias_to_upstream_model(setup_model: str, llm_router: "Router | None") -> str:
+    if llm_router is None:
+        return setup_model
+    upstream: Final = next(
+        (
+            deployment["litellm_params"]["model"]
+            for deployment in (llm_router.get_model_list() or ())
+            if deployment.get("model_name") == setup_model
+        ),
+        None,
+    )
+    if upstream is None:
+        return setup_model
+    _, provider, _, _ = litellm.get_llm_provider(model=upstream)
+    return upstream.removeprefix(f"{provider}/")
+
+
 async def vertex_ai_live_websocket_passthrough(
     websocket: WebSocket,
     model: str | None = None,
@@ -2396,51 +2484,40 @@ async def vertex_ai_live_websocket_passthrough(
     await websocket.accept()
 
     incoming_headers: Final = dict(websocket.headers)
-    vertex_credentials_config = passthrough_endpoint_router.get_vertex_credentials(
-        project_id=vertex_project,
-        location=vertex_location,
+    vertex_credentials_config: Final = _resolve_vertex_live_credentials(
+        vertex_project=vertex_project,
+        vertex_location=vertex_location,
+        model=model,
     )
 
-    if vertex_credentials_config is None:
-        # Attempt to load defaults from environment/config if not already initialised
-        passthrough_endpoint_router.set_default_vertex_config()
-        vertex_credentials_config = passthrough_endpoint_router.get_vertex_credentials(
-            project_id=vertex_project,
-            location=vertex_location,
-        )
-
-    resolved_project = vertex_project
-    resolved_location: str | None = vertex_location
-    credentials_value: str | None = None
-
-    if vertex_credentials_config is not None:
-        resolved_project = resolved_project or vertex_credentials_config.vertex_project
-        temp_location: Final = resolved_location or vertex_credentials_config.vertex_location
-        # Ensure resolved_location is a string
-        if isinstance(temp_location, dict) or temp_location is not None:
-            resolved_location = str(temp_location)
-        else:
-            resolved_location = None
-        credentials_value = (
-            str(vertex_credentials_config.vertex_credentials)
-            if vertex_credentials_config.vertex_credentials is not None
-            else None
-        )
+    configured_project: Final = vertex_project or (
+        vertex_credentials_config.vertex_project if vertex_credentials_config is not None else None
+    )
+    configured_location: Final = vertex_location or (
+        vertex_credentials_config.vertex_location if vertex_credentials_config is not None else None
+    )
+    credentials_value: Final = (
+        str(vertex_credentials_config.vertex_credentials)
+        if vertex_credentials_config is not None and vertex_credentials_config.vertex_credentials is not None
+        else None
+    )
 
     try:
-        resolved_location = resolved_location or (vertex_llm_base.get_default_vertex_location())
-        if model:
-            resolved_location = vertex_llm_base.get_vertex_region(
-                vertex_region=resolved_location,
+        resolved_location: Final = (
+            vertex_llm_base.get_vertex_region(
+                vertex_region=configured_location or vertex_llm_base.get_default_vertex_location(),
                 model=model,
             )
+            if model
+            else configured_location or vertex_llm_base.get_default_vertex_location()
+        )
 
         (
             access_token,
             resolved_project,
         ) = await vertex_llm_base._ensure_access_token_async(
             credentials=credentials_value,
-            project_id=resolved_project,
+            project_id=configured_project,
             custom_llm_provider="vertex_ai_beta",
         )
     except Exception as e:
@@ -2453,7 +2530,7 @@ async def vertex_ai_live_websocket_passthrough(
                 request_data={},
             )
         if websocket.client_state != WebSocketState.DISCONNECTED:
-            await websocket.close(code=1011, reason="Vertex AI authentication failed")
+            await websocket.close(code=1011, reason=VERTEX_LIVE_UNCONFIGURED_CLOSE_REASON)
         return
 
     host_location: Final = resolved_location or vertex_llm_base.get_default_vertex_location()
@@ -2485,6 +2562,11 @@ async def vertex_ai_live_websocket_passthrough(
         forward_headers=False,
         endpoint="/vertex_ai/live",
         accept_websocket=False,
+        setup_model_rewriter=_build_vertex_live_setup_model_rewriter(
+            vertex_project=resolved_project,
+            vertex_location=resolved_location,
+            llm_router=_get_llm_router(),
+        ),
     )
 
 
diff --git a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
index 0df0aaa1bcd..d68ef8019d2 100644
--- a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
+++ b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
@@ -5,7 +5,7 @@ import json
 import posixpath
 import traceback
 from base64 import b64encode
-from collections.abc import AsyncGenerator, Callable, Mapping
+from collections.abc import AsyncGenerator, Callable, Iterable, Mapping
 from datetime import datetime
 from itertools import groupby
 from typing import Any, Final, TypedDict, cast
@@ -32,11 +32,15 @@ from websockets.exceptions import (
     ConnectionClosedOK,
     InvalidStatus,
 )
+from websockets.frames import Close
 
 import litellm
 from litellm._logging import verbose_proxy_logger
 from litellm._uuid import uuid
-from litellm.constants import MAXIMUM_TRACEBACK_LINES_TO_LOG
+from litellm.constants import (
+    MAXIMUM_TRACEBACK_LINES_TO_LOG,
+    WEBSOCKET_CLOSE_REASON_MAX_BYTES,
+)
 from litellm.integrations.custom_guardrail import CustomGuardrail
 from litellm.integrations.custom_logger import CustomLogger
 from litellm.litellm_core_utils.core_helpers import (
@@ -1890,6 +1894,52 @@ def create_websocket_passthrough_route(
     return websocket_endpoint_func
 
 
+def _rewrite_vertex_live_setup_model(text_data: str, setup_model_rewriter: Callable[[str], str] | None) -> str:
+    """
+    Rewrite the model of a Vertex AI Live ``setup`` frame, leaving every other frame byte-identical
+    """
+    if setup_model_rewriter is None:
+        return text_data
+    try:
+        message: Final = json.loads(text_data)
+    except json.JSONDecodeError:
+        return text_data
+    if not isinstance(message, dict):
+        return text_data
+    setup: Final = message.get("setup")
+    if not isinstance(setup, dict):
+        return text_data
+    setup_model: Final = setup.get("model")
+    if not isinstance(setup_model, str):
+        return text_data
+    rewritten_model: Final = setup_model_rewriter(setup_model)
+    if rewritten_model == setup_model:
+        return text_data
+    return json.dumps({**message, "setup": {**setup, "model": rewritten_model}})  # mutable-ok: one-shot json payload
+
+
+def _truncated_close_reason(reason: str) -> str:
+    """
+    Fit a close reason inside the byte budget a WebSocket close frame allows, without splitting a character
+    """
+    encoded: Final = reason.encode("utf-8")
+    if len(encoded) <= WEBSOCKET_CLOSE_REASON_MAX_BYTES:
+        return reason
+    return encoded[:WEBSOCKET_CLOSE_REASON_MAX_BYTES].decode("utf-8", errors="ignore")
+
+
+def _upstream_close_to_relay(task_results: Iterable[object]) -> Close | None:
+    """
+    The upstream close worth telling the client about: anything other than a plain, reasonless normal close
+    """
+    upstream_close: Final = next((result for result in task_results if isinstance(result, Close)), None)
+    if upstream_close is None:
+        return None
+    if upstream_close.code == 1000 and upstream_close.reason == "":
+        return None
+    return upstream_close
+
+
 async def websocket_passthrough_request(
     websocket: WebSocket,
     target: str,
@@ -1899,6 +1949,7 @@ async def websocket_passthrough_request(
     endpoint: str | None = None,
     cost_per_request: float | None = None,
     accept_websocket: bool = True,
+    setup_model_rewriter: Callable[[str], str] | None = None,
 ):
     """
     WebSocket passthrough request handler.
@@ -1911,6 +1962,7 @@ async def websocket_passthrough_request(
         forward_headers: Whether to forward incoming headers
         endpoint: The endpoint path (for logging purposes)
         cost_per_request: Optional field - cost per request to the target endpoint
+        setup_model_rewriter: Optional rewrite of the setup frame's model before it reaches the upstream
     """
     from litellm.litellm_core_utils.litellm_logging import Logging
     from litellm.proxy.proxy_server import proxy_logging_obj
@@ -2100,7 +2152,7 @@ async def websocket_passthrough_request(
                                     )
                                     # Not a JSON message or doesn't contain setup data
 
-                            await upstream_ws.send(text_data)
+                            await upstream_ws.send(_rewrite_vertex_live_setup_model(text_data, setup_model_rewriter))
                         elif bytes_data is not None:
                             await upstream_ws.send(bytes_data)
                 except asyncio.CancelledError:
@@ -2111,8 +2163,8 @@ async def websocket_passthrough_request(
                     )
                     await upstream_ws.close()
 
-            async def forward_upstream_to_client() -> None:
-                """Forward messages from upstream to client WebSocket"""
+            async def forward_upstream_to_client() -> Close | None:
+                """Forward messages from upstream to client WebSocket, returning the upstream's close frame"""
                 try:
                     # Wait for the first response from upstream
                     raw_response = await upstream_ws.recv(decode=False)
@@ -2177,6 +2229,7 @@ async def websocket_passthrough_request(
 
                 except (ConnectionClosedOK, ConnectionClosedError) as e:
                     verbose_proxy_logger.debug("Upstream WebSocket connection closed: %s", e)
+                    return e.rcvd
                 except asyncio.CancelledError:
                     verbose_proxy_logger.debug("asyncio.CancelledError in forward_upstream_to_client")
                     raise
@@ -2209,6 +2262,13 @@ async def websocket_passthrough_request(
                 if exception is not None:
                     raise exception
 
+            upstream_close: Final = _upstream_close_to_relay(task.result() for task in done)
+            if upstream_close is not None and websocket.application_state != WebSocketState.DISCONNECTED:
+                await websocket.close(
+                    code=upstream_close.code,
+                    reason=_truncated_close_reason(upstream_close.reason),
+                )
+
             end_time: Final = datetime.now()
 
             # Update passthrough logging payload with response data
@@ -2325,7 +2385,10 @@ async def websocket_passthrough_request(
         if websocket.client_state != WebSocketState.DISCONNECTED:
             await websocket.close(code=1011, reason="WebSocket passthrough error")
     finally:
-        if websocket.client_state != WebSocketState.DISCONNECTED:
+        if (
+            websocket.client_state != WebSocketState.DISCONNECTED
+            and websocket.application_state != WebSocketState.DISCONNECTED
+        ):
             await websocket.close()
 
 
diff --git a/litellm/proxy/pass_through_endpoints/passthrough_endpoint_router.py b/litellm/proxy/pass_through_endpoints/passthrough_endpoint_router.py
index 1d2b4504d61..e7887e33ca6 100644
--- a/litellm/proxy/pass_through_endpoints/passthrough_endpoint_router.py
+++ b/litellm/proxy/pass_through_endpoints/passthrough_endpoint_router.py
@@ -10,7 +10,7 @@ from litellm.litellm_core_utils.credential_accessor import CredentialAccessor
 from litellm.secret_managers.main import get_secret_str
 from litellm.types.llms.vertex_ai import VERTEX_CREDENTIALS_TYPES
 from litellm.types.passthrough_endpoints.vertex_ai import VertexPassThroughCredentials
-from litellm.types.router import LiteLLMParamsTypedDict
+from litellm.types.router import DeploymentTypedDict, LiteLLMParamsTypedDict
 
 if TYPE_CHECKING:
     from litellm.router import Router
@@ -120,6 +120,69 @@ class PassthroughEndpointRouter:
             return None
         return provider
 
+    def get_vertex_credentials_from_router_deployments(self, model: str | None) -> VertexPassThroughCredentials | None:
+        """
+        Resolve vertex pass-through credentials from the live router deployments flagged ``use_in_pass_through``.
+
+        ``deployment_key_to_vertex_credentials`` is only reachable when the caller names a project and location,
+        which WebSocket clients never do, so DB-stored deployments need this lookup to be usable at all.
+        """
+        llm_router: Final = self.llm_router_getter()
+        if llm_router is None:
+            return None
+        resolved: Final = tuple(
+            (deployment, credentials)
+            for deployment in (llm_router.get_model_list() or ())
+            if (credentials := self._resolve_vertex_deployment_credentials(deployment["litellm_params"])) is not None
+        )
+        if len(resolved) == 0:
+            return None
+        return next(
+            (
+                credentials
+                for deployment, credentials in resolved
+                if model is not None and self._deployment_matches_model(deployment, model)
+            ),
+            resolved[0][1],
+        )
+
+    def _resolve_vertex_deployment_credentials(
+        self, litellm_params: LiteLLMParamsTypedDict
+    ) -> VertexPassThroughCredentials | None:
+        if litellm_params.get("use_in_pass_through") is not True:
+            return None
+        if self._get_deployment_provider(litellm_params) != "vertex_ai":
+            return None
+        credential_name: Final = litellm_params.get("litellm_credential_name")
+        credential_values: Final = (
+            CredentialAccessor.get_credential_values(credential_name) if credential_name is not None else None
+        )
+        vertex_project: Final = _get_str_value(credential_values, "vertex_project") or litellm_params.get(
+            "vertex_project"
+        )
+        vertex_location: Final = _get_str_value(credential_values, "vertex_location") or litellm_params.get(
+            "vertex_location"
+        )
+        vertex_credentials: Final = _get_str_value(credential_values, "vertex_credentials") or litellm_params.get(
+            "vertex_credentials"
+        )
+        if vertex_project is None or vertex_location is None:
+            return None
+        return VertexPassThroughCredentials(
+            vertex_project=vertex_project,
+            vertex_location=vertex_location,
+            vertex_credentials=vertex_credentials,
+        )
+
+    @staticmethod
+    def _deployment_matches_model(deployment: DeploymentTypedDict, model: str) -> bool:
+        upstream_model: Final = deployment["litellm_params"].get("model")
+        return model in (
+            deployment.get("model_name"),
+            upstream_model,
+            upstream_model.split("/", 1)[-1] if upstream_model is not None else None,
+        )
+
     def _get_vertex_env_vars(self) -> VertexPassThroughCredentials:
         """
         Helper to get vertex pass through config from environment variables
diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_llm_pass_through_endpoints.py b/tests/test_litellm/proxy/pass_through_endpoints/test_llm_pass_through_endpoints.py
index a9454854948..5ed974c7a47 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_llm_pass_through_endpoints.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_llm_pass_through_endpoints.py
@@ -3887,3 +3887,104 @@ class TestComprehendMedicalProxyRoute:
                 user_api_key_dict=Mock(),
             )
         assert exc_info.value.status_code == 400
+
+
+class TestVertexAILiveWebsocketPassthrough:
+    def _websocket(self):
+        from starlette.websockets import WebSocketState
+
+        websocket = MagicMock()
+        websocket.accept = AsyncMock()
+        websocket.close = AsyncMock()
+        websocket.headers = {}
+        websocket.client_state = WebSocketState.CONNECTED
+        return websocket
+
+    def _clear_vertex_env(self, monkeypatch):
+        monkeypatch.delenv("DEFAULT_VERTEXAI_PROJECT", raising=False)
+        monkeypatch.delenv("DEFAULT_VERTEXAI_LOCATION", raising=False)
+        monkeypatch.delenv("DEFAULT_GOOGLE_APPLICATION_CREDENTIALS", raising=False)
+
+    @pytest.mark.asyncio
+    async def test_uses_db_deployment_credentials_without_query_params(self, monkeypatch):
+        from litellm.proxy.pass_through_endpoints import (
+            llm_passthrough_endpoints as passthrough_module,
+        )
+
+        llm_router = litellm.Router(
+            model_list=[
+                {
+                    "model_name": "gemini-live",
+                    "litellm_params": {
+                        "model": "vertex_ai/gemini-live-2.5-flash",
+                        "use_in_pass_through": True,
+                        "vertex_project": "proj-db",
+                        "vertex_location": "global",
+                        "vertex_credentials": '{"type": "service_account"}',
+                    },
+                }
+            ]
+        )
+        monkeypatch.setattr("litellm.proxy.proxy_server.llm_router", llm_router)
+        monkeypatch.setattr(
+            passthrough_module.passthrough_endpoint_router, "default_vertex_config", None
+        )
+        self._clear_vertex_env(monkeypatch)
+        websocket = self._websocket()
+        ensure_token = AsyncMock(return_value=("token-abc", "proj-db"))
+        ws_passthrough = AsyncMock()
+
+        with (
+            patch.object(passthrough_module.vertex_llm_base, "_ensure_access_token_async", ensure_token),
+            patch.object(passthrough_module, "websocket_passthrough_request", ws_passthrough),
+        ):
+            await passthrough_module.vertex_ai_live_websocket_passthrough(
+                websocket=websocket,
+                user_api_key_dict=UserAPIKeyAuth(),
+            )
+
+        ensure_token.assert_awaited_once_with(
+            credentials='{"type": "service_account"}',
+            project_id="proj-db",
+            custom_llm_provider="vertex_ai_beta",
+        )
+        passthrough_kwargs = ws_passthrough.await_args.kwargs
+        assert passthrough_kwargs["target"] == (
+            "wss://aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent"
+        )
+        assert passthrough_kwargs["custom_headers"]["Authorization"] == "Bearer token-abc"
+        rewriter = passthrough_kwargs["setup_model_rewriter"]
+        assert rewriter("gemini-live") == (
+            "projects/proj-db/locations/global/publishers/google/models/gemini-live-2.5-flash"
+        )
+        websocket.close.assert_not_awaited()
+
+    @pytest.mark.asyncio
+    async def test_credential_failure_close_names_configuration_options(self, monkeypatch):
+        from litellm.proxy.pass_through_endpoints import (
+            llm_passthrough_endpoints as passthrough_module,
+        )
+
+        monkeypatch.setattr("litellm.proxy.proxy_server.llm_router", None)
+        monkeypatch.setattr(
+            passthrough_module.passthrough_endpoint_router, "default_vertex_config", None
+        )
+        self._clear_vertex_env(monkeypatch)
+        websocket = self._websocket()
+        ensure_token = AsyncMock(side_effect=Exception("Unable to find your credentials"))
+
+        with (
+            patch.object(passthrough_module.vertex_llm_base, "_ensure_access_token_async", ensure_token),
+            patch("litellm.proxy.proxy_server.proxy_logging_obj") as mock_proxy_logging,
+        ):
+            mock_proxy_logging.post_call_failure_hook = AsyncMock()
+            await passthrough_module.vertex_ai_live_websocket_passthrough(
+                websocket=websocket,
+                user_api_key_dict=UserAPIKeyAuth(),
+            )
+
+        close_kwargs = websocket.close.await_args.kwargs
+        assert close_kwargs["code"] == 1011
+        assert "use_in_pass_through" in close_kwargs["reason"]
+        assert "default_vertex_config" in close_kwargs["reason"]
+        assert len(close_kwargs["reason"].encode("utf-8")) <= 123
diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
index b1b934b0949..844aa099541 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
@@ -4994,6 +4994,212 @@ async def test_websocket_passthrough_forwards_non_ascii_first_frame():
     assert all(call.kwargs.get("code") != 1011 for call in websocket.close.await_args_list)
 
 
+class ClosingUpstreamWebSocket:
+    def __init__(self, close_exc: Exception):
+        self._close_exc = close_exc
+        self.close = AsyncMock()
+        self.send = AsyncMock()
+
+    async def recv(self, decode: bool = True):
+        raise self._close_exc
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        raise StopAsyncIteration
+
+
+class RecordingUpstreamWebSocket:
+    def __init__(self):
+        self.close = AsyncMock()
+        self.send = AsyncMock()
+
+    async def recv(self, decode: bool = True):
+        await asyncio.Event().wait()
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        raise StopAsyncIteration
+
+
+def _client_websocket(receive):
+    from starlette.websockets import WebSocketState
+
+    websocket = MagicMock()
+    websocket.accept = AsyncMock()
+    websocket.send_text = AsyncMock()
+    websocket.send_bytes = AsyncMock()
+    websocket.receive = receive
+    websocket.headers = {}
+    websocket.client_state = WebSocketState.CONNECTED
+    websocket.application_state = WebSocketState.CONNECTED
+
+    def _mark_closed(*args, **kwargs):
+        websocket.application_state = WebSocketState.DISCONNECTED
+
+    websocket.close = AsyncMock(side_effect=_mark_closed)
+    return websocket
+
+
+@contextmanager
+def _patched_websocket_passthrough_environment(upstream_ws):
+    with (
+        patch("litellm.proxy.proxy_server.proxy_logging_obj") as mock_proxy_logging,
+        patch(
+            "litellm.proxy.pass_through_endpoints.pass_through_endpoints.connect",
+            return_value=FakeUpstreamConnect(upstream_ws),
+        ),
+        patch(
+            "litellm.proxy.pass_through_endpoints.pass_through_endpoints.GLOBAL_LOGGING_WORKER"
+        ) as mock_worker,
+    ):
+        mock_proxy_logging.pre_call_hook = AsyncMock(return_value={})
+        mock_proxy_logging.post_call_success_hook = AsyncMock()
+        mock_proxy_logging.post_call_failure_hook = AsyncMock()
+        mock_worker.ensure_initialized_and_enqueue = MagicMock(
+            side_effect=lambda async_coroutine: async_coroutine.close()
+        )
+        yield
+
+
+async def _pending_receive():
+    await asyncio.Event().wait()
+
+
+@pytest.mark.asyncio
+async def test_websocket_passthrough_relays_upstream_policy_close_to_client():
+    from websockets.exceptions import ConnectionClosedError
+    from websockets.frames import Close
+
+    upstream_reason = "Publisher Model `projects/p/locations/global/publishers/google/models/nope` was not found"
+    upstream_ws = ClosingUpstreamWebSocket(
+        ConnectionClosedError(
+            rcvd=Close(1008, upstream_reason),
+            sent=Close(1008, ""),
+            rcvd_then_sent=True,
+        )
+    )
+    websocket = _client_websocket(_pending_receive)
+
+    with _patched_websocket_passthrough_environment(upstream_ws):
+        await websocket_passthrough_request(
+            websocket=websocket,
+            target="wss://aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent",
+            custom_headers={"Authorization": "Bearer token"},
+            user_api_key_dict=UserAPIKeyAuth(),
+            forward_headers=False,
+            endpoint="/vertex_ai/live",
+            accept_websocket=False,
+        )
+
+    websocket.close.assert_awaited_once_with(code=1008, reason=upstream_reason)
+
+
+@pytest.mark.asyncio
+async def test_websocket_passthrough_keeps_normal_upstream_close_normal():
+    from websockets.exceptions import ConnectionClosedOK
+    from websockets.frames import Close
+
+    upstream_ws = ClosingUpstreamWebSocket(
+        ConnectionClosedOK(rcvd=Close(1000, ""), sent=Close(1000, ""), rcvd_then_sent=True)
+    )
+    websocket = _client_websocket(_pending_receive)
+
+    with _patched_websocket_passthrough_environment(upstream_ws):
+        await websocket_passthrough_request(
+            websocket=websocket,
+            target="wss://aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent",
+            custom_headers={"Authorization": "Bearer token"},
+            user_api_key_dict=UserAPIKeyAuth(),
+            forward_headers=False,
+            endpoint="/vertex_ai/live",
+            accept_websocket=False,
+        )
+
+    websocket.close.assert_awaited_once_with()
+
+
+async def _run_setup_rewrite_passthrough(setup_model: str, llm_router) -> str:
+    from litellm.proxy.pass_through_endpoints.llm_passthrough_endpoints import (
+        _build_vertex_live_setup_model_rewriter,
+    )
+
+    upstream_ws = RecordingUpstreamWebSocket()
+    setup_frame = json.dumps({"setup": {"model": setup_model, "generationConfig": {"responseModalities": ["TEXT"]}}})
+    websocket = _client_websocket(
+        AsyncMock(
+            side_effect=[
+                {"type": "websocket.receive", "text": setup_frame},
+                {"type": "websocket.disconnect"},
+            ]
+        )
+    )
+
+    with _patched_websocket_passthrough_environment(upstream_ws):
+        await websocket_passthrough_request(
+            websocket=websocket,
+            target="wss://aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent",
+            custom_headers={"Authorization": "Bearer token"},
+            user_api_key_dict=UserAPIKeyAuth(),
+            forward_headers=False,
+            endpoint="/vertex_ai/live",
+            accept_websocket=False,
+            setup_model_rewriter=_build_vertex_live_setup_model_rewriter(
+                vertex_project="proj-db",
+                vertex_location="global",
+                llm_router=llm_router,
+            ),
+        )
+
+    upstream_ws.send.assert_awaited_once()
+    return upstream_ws.send.await_args.args[0]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "setup_model",
+    ["gemini-live-2.5-flash", "publishers/google/models/gemini-live-2.5-flash"],
+)
+async def test_websocket_passthrough_rewrites_setup_model_to_full_resource(setup_model):
+    sent_frame = await _run_setup_rewrite_passthrough(setup_model, llm_router=None)
+
+    sent_setup = json.loads(sent_frame)["setup"]
+    assert sent_setup["model"] == "projects/proj-db/locations/global/publishers/google/models/gemini-live-2.5-flash"
+    assert sent_setup["generationConfig"] == {"responseModalities": ["TEXT"]}
+
+
+@pytest.mark.asyncio
+async def test_websocket_passthrough_rewrites_gateway_alias_setup_model():
+    llm_router = litellm.Router(
+        model_list=[
+            {
+                "model_name": "gemini-live",
+                "litellm_params": {"model": "vertex_ai/gemini-live-2.5-flash"},
+            }
+        ]
+    )
+
+    sent_frame = await _run_setup_rewrite_passthrough("gemini-live", llm_router=llm_router)
+
+    sent_setup = json.loads(sent_frame)["setup"]
+    assert sent_setup["model"] == "projects/proj-db/locations/global/publishers/google/models/gemini-live-2.5-flash"
+
+
+@pytest.mark.asyncio
+async def test_websocket_passthrough_leaves_full_resource_setup_model_untouched():
+    full_resource = "projects/other/locations/us-central1/publishers/google/models/gemini-2.0-flash-live-preview-04-09"
+
+    sent_frame = await _run_setup_rewrite_passthrough(full_resource, llm_router=None)
+
+    assert json.loads(sent_frame)["setup"]["model"] == full_resource
+    assert sent_frame == json.dumps(
+        {"setup": {"model": full_resource, "generationConfig": {"responseModalities": ["TEXT"]}}}
+    )
+
+
 def _passthrough_kwargs_for_reservation(
     user_api_key_dict: UserAPIKeyAuth, parsed_body: Optional[dict] = None
 ) -> dict:
diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_endpoint_router.py b/tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_endpoint_router.py
index d7266ecd9ed..7816178471f 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_endpoint_router.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_endpoint_router.py
@@ -172,3 +172,144 @@ def test_returns_none_when_no_router_and_no_env():
     passthrough_router = _passthrough_router(None)
 
     assert passthrough_router.get_credentials(custom_llm_provider="openai", region_name=None) is None
+
+
+def _vertex_credential(name: str, values: dict) -> CredentialItem:
+    return CredentialItem(credential_name=name, credential_values=values, credential_info={})
+
+
+def _vertex_deployment(model_name: str, model: str, **litellm_params) -> dict:
+    return {
+        "model_name": model_name,
+        "litellm_params": {"model": model, "use_in_pass_through": True, **litellm_params},
+    }
+
+
+def test_vertex_deployment_resolves_via_named_credential():
+    CredentialAccessor.upsert_credentials(
+        [
+            _vertex_credential(
+                "cred_gcp",
+                {
+                    "vertex_project": "proj-db",
+                    "vertex_location": "global",
+                    "vertex_credentials": '{"type": "service_account"}',
+                },
+            )
+        ]
+    )
+    llm_router = litellm.Router(
+        model_list=[
+            _vertex_deployment(
+                "gemini-live", "vertex_ai/gemini-live-2.5-flash", litellm_credential_name="cred_gcp"
+            )
+        ]
+    )
+    passthrough_router = _passthrough_router(llm_router)
+
+    resolved = passthrough_router.get_vertex_credentials_from_router_deployments(model=None)
+
+    assert resolved is not None
+    assert resolved.vertex_project == "proj-db"
+    assert resolved.vertex_location == "global"
+    assert resolved.vertex_credentials == '{"type": "service_account"}'
+
+
+def test_vertex_deployment_resolves_from_inline_litellm_params():
+    llm_router = litellm.Router(
+        model_list=[
+            _vertex_deployment(
+                "gemini-live",
+                "vertex_ai/gemini-live-2.5-flash",
+                vertex_project="proj-inline",
+                vertex_location="us-east4",
+                vertex_credentials='{"type": "service_account", "project_id": "proj-inline"}',
+            )
+        ]
+    )
+    passthrough_router = _passthrough_router(llm_router)
+
+    resolved = passthrough_router.get_vertex_credentials_from_router_deployments(model=None)
+
+    assert resolved is not None
+    assert resolved.vertex_project == "proj-inline"
+    assert resolved.vertex_location == "us-east4"
+    assert resolved.vertex_credentials == '{"type": "service_account", "project_id": "proj-inline"}'
+
+
+def _two_vertex_deployments_router() -> litellm.Router:
+    return litellm.Router(
+        model_list=[
+            _vertex_deployment(
+                "gemini-flash",
+                "vertex_ai/gemini-2.5-flash",
+                vertex_project="proj-first",
+                vertex_location="us-central1",
+            ),
+            _vertex_deployment(
+                "gemini-live",
+                "vertex_ai/gemini-live-2.5-flash",
+                vertex_project="proj-live",
+                vertex_location="global",
+            ),
+        ]
+    )
+
+
+def test_vertex_model_hint_prefers_matching_deployment():
+    passthrough_router = _passthrough_router(_two_vertex_deployments_router())
+
+    by_alias = passthrough_router.get_vertex_credentials_from_router_deployments(model="gemini-live")
+    by_upstream_id = passthrough_router.get_vertex_credentials_from_router_deployments(
+        model="gemini-live-2.5-flash"
+    )
+
+    assert by_alias is not None and by_alias.vertex_project == "proj-live"
+    assert by_upstream_id is not None and by_upstream_id.vertex_project == "proj-live"
+
+
+def test_vertex_unmatched_hint_falls_back_to_first_flagged_deployment():
+    passthrough_router = _passthrough_router(_two_vertex_deployments_router())
+
+    unmatched = passthrough_router.get_vertex_credentials_from_router_deployments(model="unknown-model")
+    no_hint = passthrough_router.get_vertex_credentials_from_router_deployments(model=None)
+
+    assert unmatched is not None and unmatched.vertex_project == "proj-first"
+    assert no_hint is not None and no_hint.vertex_project == "proj-first"
+
+
+def test_no_flagged_vertex_deployment_returns_none():
+    llm_router = litellm.Router(
+        model_list=[
+            {
+                "model_name": "gemini-live",
+                "litellm_params": {
+                    "model": "vertex_ai/gemini-live-2.5-flash",
+                    "vertex_project": "proj-unflagged",
+                    "vertex_location": "global",
+                },
+            },
+            _flagged_deployment("openai/gpt-4o", api_key="sk-flagged"),
+        ]
+    )
+    passthrough_router = _passthrough_router(llm_router)
+
+    assert passthrough_router.get_vertex_credentials_from_router_deployments(model=None) is None
+    assert _passthrough_router(None).get_vertex_credentials_from_router_deployments(model=None) is None
+
+
+def test_vertex_deployment_with_deleted_credential_is_skipped(monkeypatch):
+    CredentialAccessor.upsert_credentials(
+        [_vertex_credential("cred_gone", {"vertex_project": "proj-db", "vertex_location": "global"})]
+    )
+    llm_router = litellm.Router(
+        model_list=[
+            _vertex_deployment(
+                "gemini-live", "vertex_ai/gemini-live-2.5-flash", litellm_credential_name="cred_gone"
+            )
+        ]
+    )
+    passthrough_router = _passthrough_router(llm_router)
+    monkeypatch.setattr(litellm, "credential_list", [])
+
+    assert passthrough_router.get_vertex_credentials_from_router_deployments(model=None) is None

From 9271133bebedd2ece0fe23535fd783d69cae2547 Mon Sep 17 00:00:00 2001
From: Mateo <edgetonmas@gmail.com>
Date: Thu, 20 Aug 2026 02:02:00 -0700
Subject: [PATCH 05/35] fix(realtime): bound Vertex credential resolution and
 make realtime failures loud

A /v1/realtime connection to a Vertex AI Live model accepted the WebSocket
upgrade and then went silent: a stalled Google OAuth token fetch blocked the
handler before any session event, and the eventual failure closed the socket
with a bare 1011 and no error event, so callers saw an open socket, no frames,
and no reason.

Bound the pre-session token fetch with
REALTIME_CREDENTIAL_RESOLUTION_TIMEOUT_SECONDS (20s default) and, on any
realtime failure, send an OpenAI-style error event before closing with a reason
that names the failure. Close reasons are truncated by bytes, not characters,
since an over-long reason makes the close frame itself fail.
---
 litellm/constants.py                          |   3 +
 litellm/litellm_core_utils/realtime_errors.py |  31 +++++
 litellm/llms/custom_httpx/llm_http_handler.py |  14 ++-
 litellm/proxy/proxy_server.py                 |  21 +++-
 litellm/realtime_api/main.py                  |  35 +++++-
 litellm/types/realtime.py                     |  12 +-
 .../test_realtime_errors.py                   |  47 ++++++++
 .../custom_httpx/test_llm_http_handler.py     |  68 +++++++++++
 .../test_realtime_webrtc_endpoints.py         | 108 ++++++++++++++++++
 tests/test_litellm/realtime_api/test_main.py  |  63 ++++++++++
 10 files changed, 392 insertions(+), 10 deletions(-)
 create mode 100644 litellm/litellm_core_utils/realtime_errors.py
 create mode 100644 tests/test_litellm/litellm_core_utils/test_realtime_errors.py

diff --git a/litellm/constants.py b/litellm/constants.py
index facfc6f7c19..eff82bc268b 100644
--- a/litellm/constants.py
+++ b/litellm/constants.py
@@ -243,6 +243,9 @@ AIOHTTP_NEEDS_CLEANUP_CLOSED: Final = (3, 13, 0) <= sys.version_info < (
 # https://github.com/openai/openai-agents-python/blob/cf1b933660e44fd37b4350c41febab8221801409/src/agents/realtime/openai_realtime.py#L235
 _max_size_env: Final = os.getenv("REALTIME_WEBSOCKET_MAX_MESSAGE_SIZE_BYTES")
 REALTIME_WEBSOCKET_MAX_MESSAGE_SIZE_BYTES: Final = int(_max_size_env) if _max_size_env is not None else None
+REALTIME_CREDENTIAL_RESOLUTION_TIMEOUT_SECONDS: Final = float(
+    os.getenv("REALTIME_CREDENTIAL_RESOLUTION_TIMEOUT_SECONDS", "20.0")
+)
 
 # SSL/TLS cipher configuration for faster handshakes
 # Strategy: Strongly prefer fast modern ciphers, but allow fallback to commonly supported ones
diff --git a/litellm/litellm_core_utils/realtime_errors.py b/litellm/litellm_core_utils/realtime_errors.py
new file mode 100644
index 00000000000..e1b957f4325
--- /dev/null
+++ b/litellm/litellm_core_utils/realtime_errors.py
@@ -0,0 +1,31 @@
+"""Loud-failure helpers for the realtime WebSocket paths.
+
+A realtime caller that only gets a bare close frame has nothing to act on, so
+every failure surfaces as an OpenAI-style ``error`` event plus a close frame
+whose reason names the failure. Close reasons are capped at
+``WEBSOCKET_CLOSE_REASON_MAX_BYTES``: RFC 6455 control frames carry at most 125
+bytes, two of which hold the status code, and a longer reason makes the close
+frame itself fail, which is how a loud failure turns back into a silent one.
+"""
+
+import json
+from typing import Final
+
+from litellm.types.realtime import RealtimeErrorDetail, RealtimeErrorEvent
+
+WEBSOCKET_CLOSE_REASON_MAX_BYTES: Final = 123
+
+
+def realtime_error_event(message: str, error_type: str) -> str:
+    detail: Final[RealtimeErrorDetail] = {"type": error_type, "message": message}
+    event: Final[RealtimeErrorEvent] = {"type": "error", "error": detail}
+    return json.dumps(event)
+
+
+def websocket_close_reason(message: str, fallback: str) -> str:
+    encoded: Final = message.encode("utf-8")
+    if not encoded:
+        return fallback
+    if len(encoded) <= WEBSOCKET_CLOSE_REASON_MAX_BYTES:
+        return message
+    return encoded[:WEBSOCKET_CLOSE_REASON_MAX_BYTES].decode("utf-8", errors="ignore")
diff --git a/litellm/llms/custom_httpx/llm_http_handler.py b/litellm/llms/custom_httpx/llm_http_handler.py
index cc522aed1ee..9a950d7f920 100644
--- a/litellm/llms/custom_httpx/llm_http_handler.py
+++ b/litellm/llms/custom_httpx/llm_http_handler.py
@@ -20,6 +20,7 @@ from litellm._logging import _redact_string, verbose_logger
 from litellm.anthropic_beta_headers_manager import update_headers_with_filtered_beta
 from litellm.constants import REALTIME_WEBSOCKET_MAX_MESSAGE_SIZE_BYTES
 from litellm.litellm_core_utils.asyncify import run_async_function
+from litellm.litellm_core_utils.realtime_errors import realtime_error_event, websocket_close_reason
 from litellm.litellm_core_utils.realtime_streaming import RealTimeStreaming
 from litellm.litellm_core_utils.url_utils import encode_url_path_segment
 from litellm.llms.base_llm.anthropic_messages.transformation import (
@@ -5976,8 +5977,19 @@ class BaseLLMHTTPHandler:
             await websocket.close(code=e.status_code, reason=_redact_string(str(e)))
         except Exception as e:
             verbose_logger.exception("Error connecting to backend: %s", e)
+            redacted_error: Final = _redact_string(str(e))
             try:
-                await websocket.close(code=1011, reason=_redact_string(f"Internal server error: {e}"))
+                await websocket.send_text(realtime_error_event(redacted_error, error_type="server_error"))
+            except Exception:  # noqa: BLE001  # best-effort notice: a dead client socket must not skip the close below
+                verbose_logger.debug("Could not send realtime error event to client; closing anyway")
+            try:
+                await websocket.close(
+                    code=1011,
+                    reason=websocket_close_reason(
+                        _redact_string(f"Internal server error: {e}"),
+                        fallback="Internal server error",
+                    ),
+                )
             except RuntimeError as close_error:
                 if "already completed" in str(close_error) or "websocket.close" in str(close_error):
                     # The WebSocket is already closed or the response is completed, so we can ignore this error
diff --git a/litellm/proxy/proxy_server.py b/litellm/proxy/proxy_server.py
index af082f04706..4a342174277 100644
--- a/litellm/proxy/proxy_server.py
+++ b/litellm/proxy/proxy_server.py
@@ -222,7 +222,7 @@ from functools import lru_cache
 import litellm
 import litellm._redis
 from litellm import Router
-from litellm._logging import verbose_proxy_logger, verbose_router_logger
+from litellm._logging import _redact_string, verbose_proxy_logger, verbose_router_logger
 from litellm.caching.caching import DualCache, RedisCache
 from litellm.caching.redis_cluster_cache import RedisClusterCache
 from litellm.constants import (
@@ -259,6 +259,10 @@ from litellm.litellm_core_utils.core_helpers import (
 )
 from litellm.litellm_core_utils.credential_accessor import CredentialAccessor
 from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
+from litellm.litellm_core_utils.realtime_errors import (
+    realtime_error_event,
+    websocket_close_reason,
+)
 from litellm.litellm_core_utils.sensitive_data_masker import (
     SensitiveDataMasker,
     mask_sensitive_keys,
@@ -10993,9 +10997,20 @@ async def realtime_websocket_endpoint(
     except websockets.exceptions.InvalidStatusCode as e:
         verbose_proxy_logger.exception("Invalid status code")
         await websocket.close(code=e.status_code, reason="Invalid status code")
-    except Exception:
+    except Exception as e:
         verbose_proxy_logger.exception("Internal server error")
-        await websocket.close(code=1011, reason="Internal server error")
+        redacted_error: Final = _redact_string(str(e))
+        try:
+            await websocket.send_text(realtime_error_event(redacted_error, error_type="server_error"))
+        except Exception:  # noqa: BLE001  # best-effort notice: a dead client socket must not skip the close below
+            verbose_proxy_logger.debug("Could not send realtime error event to client; closing anyway")
+        try:
+            await websocket.close(
+                code=1011,
+                reason=websocket_close_reason(redacted_error, fallback="Internal server error"),
+            )
+        except Exception:  # noqa: BLE001  # the lower layer may have closed the socket already; closing twice is not an error
+            verbose_proxy_logger.debug("Could not close realtime client websocket; it is already gone")
 
 
 ######################################################################
diff --git a/litellm/realtime_api/main.py b/litellm/realtime_api/main.py
index d5195659b1c..8fde7cb75c5 100644
--- a/litellm/realtime_api/main.py
+++ b/litellm/realtime_api/main.py
@@ -1,15 +1,21 @@
 """Abstraction function for OpenAI's realtime API"""
 
+import asyncio
 import os
 from typing import Any, Final, cast
 
 import litellm
-from litellm.constants import REALTIME_WEBSOCKET_MAX_MESSAGE_SIZE_BYTES, request_timeout
+from litellm.constants import (
+    REALTIME_CREDENTIAL_RESOLUTION_TIMEOUT_SECONDS,
+    REALTIME_WEBSOCKET_MAX_MESSAGE_SIZE_BYTES,
+    request_timeout,
+)
 from litellm.litellm_core_utils.get_llm_provider_logic import get_llm_provider
 from litellm.llms.base_llm.realtime.transformation import BaseRealtimeConfig
 from litellm.llms.custom_httpx.llm_http_handler import BaseLLMHTTPHandler
 from litellm.llms.xai.common_utils import XAIModelInfo
 from litellm.secret_managers.main import get_secret_str
+from litellm.types.llms.vertex_ai import VERTEX_CREDENTIALS_TYPES
 from litellm.types.realtime import (
     RealtimeClientSecretRequest,
     RealtimeExpiresAfter,
@@ -281,6 +287,27 @@ async def arealtime_calls(
     )
 
 
+async def _resolve_vertex_access_token_bounded(
+    credentials: VERTEX_CREDENTIALS_TYPES | None,
+    project_id: str | None,
+) -> tuple[str, str]:
+    try:
+        return await asyncio.wait_for(
+            vertex_llm_base._ensure_access_token_async(
+                credentials=credentials,
+                project_id=project_id,
+                custom_llm_provider="vertex_ai",
+            ),
+            timeout=REALTIME_CREDENTIAL_RESOLUTION_TIMEOUT_SECONDS,
+        )
+    except asyncio.TimeoutError as e:
+        raise ValueError(
+            "Vertex AI realtime: timed out fetching Google OAuth access token after "
+            f"{REALTIME_CREDENTIAL_RESOLUTION_TIMEOUT_SECONDS}s; check network egress from the proxy "
+            "to the OAuth token endpoint (oauth2.googleapis.com)"
+        ) from e
+
+
 @wrapper_client
 async def _arealtime(
     model: str,
@@ -478,10 +505,9 @@ async def _arealtime(
         (
             access_token,
             resolved_project,
-        ) = await vertex_llm_base._ensure_access_token_async(
+        ) = await _resolve_vertex_access_token_bounded(
             credentials=vertex_credentials,
             project_id=vertex_project,
-            custom_llm_provider="vertex_ai",
         )
 
         vertex_realtime_config: Final = VertexAIRealtimeConfig(
@@ -559,10 +585,9 @@ async def _realtime_health_check(
         (
             access_token,
             resolved_project,
-        ) = await vertex_llm_base._ensure_access_token_async(
+        ) = await _resolve_vertex_access_token_bounded(
             credentials=VertexBase.safe_get_vertex_ai_credentials(vertex_model_params),
             project_id=VertexBase.safe_get_vertex_ai_project(vertex_model_params),
-            custom_llm_provider="vertex_ai",
         )
         vertex_realtime_config: Final = VertexAIRealtimeConfig(
             access_token=access_token,
diff --git a/litellm/types/realtime.py b/litellm/types/realtime.py
index 15238f7e13f..cbd7a8b7ecb 100644
--- a/litellm/types/realtime.py
+++ b/litellm/types/realtime.py
@@ -1,7 +1,7 @@
 from typing import Any, Literal
 
 from pydantic import BaseModel
-from typing_extensions import TypedDict
+from typing_extensions import ReadOnly, TypedDict
 
 from .llms.openai import (
     OpenAIRealtimeEvents,
@@ -152,3 +152,13 @@ class RealtimeTranscriptionSessionResponse(BaseModel):
     model_config = {"extra": "allow"}
 
     client_secret: dict[str, Any] | None = None
+
+
+class RealtimeErrorDetail(TypedDict):
+    type: ReadOnly[str]
+    message: ReadOnly[str]
+
+
+class RealtimeErrorEvent(TypedDict):
+    type: ReadOnly[Literal["error"]]
+    error: ReadOnly[RealtimeErrorDetail]
diff --git a/tests/test_litellm/litellm_core_utils/test_realtime_errors.py b/tests/test_litellm/litellm_core_utils/test_realtime_errors.py
new file mode 100644
index 00000000000..263d1654f65
--- /dev/null
+++ b/tests/test_litellm/litellm_core_utils/test_realtime_errors.py
@@ -0,0 +1,47 @@
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../../.."))
+
+from litellm.litellm_core_utils.realtime_errors import (
+    WEBSOCKET_CLOSE_REASON_MAX_BYTES,
+    realtime_error_event,
+    websocket_close_reason,
+)
+
+
+def test_realtime_error_event_shape():
+    event = json.loads(realtime_error_event("token refresh failed", error_type="server_error"))
+
+    assert event == {
+        "type": "error",
+        "error": {"type": "server_error", "message": "token refresh failed"},
+    }
+
+
+def test_websocket_close_reason_keeps_short_messages_intact():
+    assert websocket_close_reason("boom", fallback="Internal server error") == "boom"
+
+
+def test_websocket_close_reason_falls_back_on_empty_message():
+    assert websocket_close_reason("", fallback="Internal server error") == "Internal server error"
+
+
+def test_websocket_close_reason_truncates_long_ascii_message():
+    reason = websocket_close_reason("x" * 500, fallback="Internal server error")
+
+    assert len(reason.encode("utf-8")) <= WEBSOCKET_CLOSE_REASON_MAX_BYTES
+    assert reason == "x" * WEBSOCKET_CLOSE_REASON_MAX_BYTES
+
+
+def test_websocket_close_reason_truncates_multibyte_message_by_bytes():
+    """A close frame carries at most 123 bytes of reason, not 123 characters:
+    truncating by characters lets a multibyte message overflow the control
+    frame, which makes the close itself fail and leaves the caller with a bare
+    abnormal closure and no reason at all."""
+    reason = websocket_close_reason("あ" * 200, fallback="Internal server error")
+
+    assert len(reason.encode("utf-8")) <= WEBSOCKET_CLOSE_REASON_MAX_BYTES
+    assert reason == "あ" * (WEBSOCKET_CLOSE_REASON_MAX_BYTES // 3)
+    assert "�" not in reason
diff --git a/tests/test_litellm/llms/custom_httpx/test_llm_http_handler.py b/tests/test_litellm/llms/custom_httpx/test_llm_http_handler.py
index 9e9242137e6..c568b82ebba 100644
--- a/tests/test_litellm/llms/custom_httpx/test_llm_http_handler.py
+++ b/tests/test_litellm/llms/custom_httpx/test_llm_http_handler.py
@@ -1738,6 +1738,74 @@ async def test_realtime_backend_open_does_not_retry_auth_failure(rejection):
     assert fake.attempts == 1
 
 
+class _FakeClientWebSocket:
+    def __init__(self, send_error=None):
+        self.events = []
+        self._send_error = send_error
+
+    async def send_text(self, payload):
+        if self._send_error is not None:
+            raise self._send_error
+        self.events.append(("send_text", payload))
+
+    async def close(self, code=None, reason=None):
+        self.events.append(("close", (code, reason)))
+
+
+async def _run_async_realtime_with_backend_failure(client_ws):
+    import websockets.exceptions  # noqa: F401  # binds the submodule so async_realtime's except clause resolves, as in the proxy process
+
+    handler = BaseLLMHTTPHandler()
+    provider_config = Mock()
+    provider_config.get_complete_url.return_value = "wss://backend.example/live"
+    provider_config.validate_environment.return_value = {}
+
+    with patch.object(
+        handler,
+        "_open_realtime_backend_ws",
+        AsyncMock(side_effect=Exception("vertex token refresh exploded")),
+    ):
+        await handler.async_realtime(
+            model="gemini-live-2.5-flash",
+            websocket=client_ws,
+            logging_obj=Mock(),
+            provider_config=provider_config,
+            headers={},
+        )
+
+
+@pytest.mark.asyncio
+async def test_async_realtime_generic_failure_sends_error_event_then_reasoned_close():
+    """Regression for the realtime accept-then-silence hang: a generic backend
+    failure used to close the client socket without any error event, so callers
+    only saw a bare 1011. The client must receive an OpenAI-style error event
+    before the reasoned close."""
+    client_ws = _FakeClientWebSocket()
+
+    await _run_async_realtime_with_backend_failure(client_ws)
+
+    assert [name for name, _ in client_ws.events] == ["send_text", "close"]
+
+    error_event = json.loads(client_ws.events[0][1])
+    assert error_event["type"] == "error"
+    assert error_event["error"]["type"] == "server_error"
+    assert "vertex token refresh exploded" in error_event["error"]["message"]
+
+    assert client_ws.events[1][1] == (1011, "Internal server error: vertex token refresh exploded")
+
+
+@pytest.mark.asyncio
+async def test_async_realtime_error_event_send_failure_still_closes():
+    """A client socket that already dropped must not turn the loud-failure path
+    into a new exception: the error-event send may fail, but the reasoned close
+    must still be attempted."""
+    client_ws = _FakeClientWebSocket(send_error=RuntimeError("client already disconnected"))
+
+    await _run_async_realtime_with_backend_failure(client_ws)
+
+    assert client_ws.events == [("close", (1011, "Internal server error: vertex token refresh exploded"))]
+
+
 class _JSONBodyAudioTranscriptionConfig(BaseAudioTranscriptionConfig):
     def get_supported_openai_params(self, model):
         return []
diff --git a/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py b/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py
index e0e51e7b966..9840de8bcb1 100644
--- a/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py
+++ b/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py
@@ -818,6 +818,114 @@ async def test_realtime_transcription_websocket_default_model_checks_team_scope(
     assert "not allowed to access model" in close_kwargs["reason"]
 
 
+@pytest.mark.asyncio
+async def test_realtime_websocket_phase2_failure_sends_error_event_and_reasoned_close():
+    """Regression for the realtime accept-then-silence hang: a phase-2 failure
+    (routing / upstream credential resolution) used to close 1011 with the bare
+    reason "Internal server error" and no error event, leaving the client with
+    no clue what happened. The client must get an OpenAI-style error event and
+    a close reason naming the failure."""
+    from litellm.proxy import proxy_server
+
+    events = []
+
+    websocket = MagicMock()
+    websocket.headers = {}
+    websocket.scope = {"headers": []}
+    websocket.accept = AsyncMock()
+    websocket.send_text = AsyncMock(side_effect=lambda payload: events.append(("send_text", payload)))
+    websocket.close = AsyncMock(side_effect=lambda **kwargs: events.append(("close", kwargs)))
+
+    mock_processor = MagicMock()
+    mock_processor.common_processing_pre_call_logic = AsyncMock(
+        return_value=({"model": "gpt-4o-realtime-preview"}, MagicMock())
+    )
+
+    with (
+        patch(
+            "litellm.proxy.proxy_server.can_key_call_resolved_model",
+            new=AsyncMock(return_value=None),
+        ),
+        patch(
+            "litellm.proxy.proxy_server.ProxyBaseLLMRequestProcessing",
+            return_value=mock_processor,
+        ),
+        patch(
+            "litellm.proxy.proxy_server.route_request",
+            new=AsyncMock(side_effect=RuntimeError("vertex token refresh exploded")),
+        ),
+    ):
+        await proxy_server.realtime_websocket_endpoint(
+            websocket=websocket,
+            model="gpt-4o-realtime-preview",
+            intent=None,
+            guardrails=None,
+            user_api_key_dict=UserAPIKeyAuth(models=["*"]),
+        )
+
+    websocket.accept.assert_awaited_once()
+    assert [name for name, _ in events] == ["send_text", "close"]
+
+    error_event = json.loads(events[0][1])
+    assert error_event["type"] == "error"
+    assert error_event["error"]["type"] == "server_error"
+    assert "vertex token refresh exploded" in error_event["error"]["message"]
+
+    close_kwargs = events[1][1]
+    assert close_kwargs["code"] == 1011
+    assert "vertex token refresh exploded" in close_kwargs["reason"]
+    assert len(close_kwargs["reason"].encode("utf-8")) <= 123
+
+
+@pytest.mark.asyncio
+async def test_realtime_websocket_phase2_failure_on_closed_socket_does_not_escape():
+    """The lower handler layer may have already closed the client socket before
+    the phase-2 handler runs (it closes on backend failures itself, then can
+    re-raise). Send and close must each be guarded: the close is still
+    attempted after a failed send, and neither failure escapes to the ASGI
+    layer."""
+    from litellm.proxy import proxy_server
+
+    websocket = MagicMock()
+    websocket.headers = {}
+    websocket.scope = {"headers": []}
+    websocket.accept = AsyncMock()
+    websocket.send_text = AsyncMock(side_effect=RuntimeError('Cannot call "send" once a close message has been sent.'))
+    websocket.close = AsyncMock(side_effect=RuntimeError('Cannot call "send" once a close message has been sent.'))
+
+    mock_processor = MagicMock()
+    mock_processor.common_processing_pre_call_logic = AsyncMock(
+        return_value=({"model": "gpt-4o-realtime-preview"}, MagicMock())
+    )
+
+    with (
+        patch(
+            "litellm.proxy.proxy_server.can_key_call_resolved_model",
+            new=AsyncMock(return_value=None),
+        ),
+        patch(
+            "litellm.proxy.proxy_server.ProxyBaseLLMRequestProcessing",
+            return_value=mock_processor,
+        ),
+        patch(
+            "litellm.proxy.proxy_server.route_request",
+            new=AsyncMock(side_effect=RuntimeError("vertex token refresh exploded")),
+        ),
+    ):
+        await proxy_server.realtime_websocket_endpoint(
+            websocket=websocket,
+            model="gpt-4o-realtime-preview",
+            intent=None,
+            guardrails=None,
+            user_api_key_dict=UserAPIKeyAuth(models=["*"]),
+        )
+
+    websocket.close.assert_awaited_once()
+    _, close_kwargs = websocket.close.call_args
+    assert close_kwargs["code"] == 1011
+    assert "vertex token refresh exploded" in close_kwargs["reason"]
+
+
 @pytest.mark.asyncio
 async def test_transcription_sessions_encrypts_client_secret(
     proxy_app,
diff --git a/tests/test_litellm/realtime_api/test_main.py b/tests/test_litellm/realtime_api/test_main.py
index 406f5ef56d9..8ed7fb06e84 100644
--- a/tests/test_litellm/realtime_api/test_main.py
+++ b/tests/test_litellm/realtime_api/test_main.py
@@ -1,6 +1,8 @@
 import asyncio
 import os
 import sys
+import time
+from unittest.mock import MagicMock
 
 sys.path.insert(0, os.path.abspath("../../.."))
 
@@ -91,6 +93,67 @@ def test_client_secret_session_model_takes_priority_over_top_level(monkeypatch):
     assert captured["request_data"]["session"]["model"] == "gpt-realtime-session"
 
 
+@pytest.mark.asyncio
+async def test_arealtime_vertex_hung_credential_resolution_raises_promptly(monkeypatch):
+    """Regression for the realtime accept-then-silence hang: a stalled Google
+    OAuth token refresh used to block _arealtime's vertex branch unbounded
+    (minutes of zero frames for the client). It must instead raise a clear,
+    prompt error naming the credential-resolution timeout."""
+
+    async def hanging_token_refresh(**kwargs):
+        await asyncio.sleep(30)
+
+    def mock_get_llm_provider(model, api_base, api_key):
+        return model, "vertex_ai", None, api_base
+
+    monkeypatch.setattr(realtime_main, "get_llm_provider", mock_get_llm_provider)
+    monkeypatch.setattr(realtime_main.vertex_llm_base, "_ensure_access_token_async", hanging_token_refresh)
+    monkeypatch.setattr(realtime_main, "REALTIME_CREDENTIAL_RESOLUTION_TIMEOUT_SECONDS", 0.05)
+
+    start = time.monotonic()
+    with pytest.raises(ValueError, match="timed out fetching Google OAuth access token"):
+        await realtime_main._arealtime.__wrapped__(
+            model="gemini-live-2.5-flash",
+            websocket=MagicMock(),
+            litellm_logging_obj=FakeLogging(),
+            vertex_credentials="fake-credentials",
+            vertex_project="fake-project",
+            vertex_location="us-central1",
+        )
+    assert time.monotonic() - start < 5
+
+
+@pytest.mark.asyncio
+async def test_arealtime_vertex_credential_timeout_survives_thread_offloaded_refresh(monkeypatch):
+    """The real stall is a blocking google-auth refresh that runs in a worker
+    thread via asyncify, not a plain awaitable sleep. A timeout that only bounds
+    cancellable awaits would leave that shape hanging, so bound the shape the
+    proxy actually runs."""
+    from litellm.litellm_core_utils.asyncify import asyncify
+
+    async def thread_offloaded_hanging_refresh(**kwargs):
+        return await asyncify(time.sleep)(30)
+
+    def mock_get_llm_provider(model, api_base, api_key):
+        return model, "vertex_ai", None, api_base
+
+    monkeypatch.setattr(realtime_main, "get_llm_provider", mock_get_llm_provider)
+    monkeypatch.setattr(realtime_main.vertex_llm_base, "_ensure_access_token_async", thread_offloaded_hanging_refresh)
+    monkeypatch.setattr(realtime_main, "REALTIME_CREDENTIAL_RESOLUTION_TIMEOUT_SECONDS", 0.05)
+
+    start = time.monotonic()
+    with pytest.raises(ValueError, match="timed out fetching Google OAuth access token"):
+        await realtime_main._arealtime.__wrapped__(
+            model="gemini-live-2.5-flash",
+            websocket=MagicMock(),
+            litellm_logging_obj=FakeLogging(),
+            vertex_credentials="fake-credentials",
+            vertex_project="fake-project",
+            vertex_location="us-central1",
+        )
+    assert time.monotonic() - start < 5
+
+
 def test_client_secret_forwards_nested_transcription_model_untouched(monkeypatch):
     captured = _run_client_secret(
         session={

From b9d977aeeefc94e249b0ea63106ee81c399ecf1a Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 02:15:17 -0700
Subject: [PATCH 06/35] fix: guard vertex live passthrough provider lookup and
 close-code relay

---
 .../llm_passthrough_endpoints.py              |  9 ++--
 .../pass_through_endpoints.py                 |  9 +++-
 .../test_pass_through_endpoints.py            | 43 +++++++++++++++++++
 3 files changed, 56 insertions(+), 5 deletions(-)

diff --git a/litellm/proxy/pass_through_endpoints/llm_passthrough_endpoints.py b/litellm/proxy/pass_through_endpoints/llm_passthrough_endpoints.py
index 050ad0fd627..c2b221b1f7a 100644
--- a/litellm/proxy/pass_through_endpoints/llm_passthrough_endpoints.py
+++ b/litellm/proxy/pass_through_endpoints/llm_passthrough_endpoints.py
@@ -2397,8 +2397,8 @@ def _resolve_vertex_live_credentials(
     model: str | None,
 ) -> VertexPassThroughCredentials | None:
     """
-    Resolution order: credentials registered for the requested project/location, then any DB model entry
-    flagged ``use_in_pass_through``, then ``default_vertex_config`` and the ``DEFAULT_VERTEXAI_*`` env vars
+    Resolution order: an explicit project/location registration or ``default_vertex_config``, then any DB model
+    entry flagged ``use_in_pass_through``, then the ``DEFAULT_VERTEXAI_*`` env vars
     """
     keyed: Final = passthrough_endpoint_router.get_vertex_credentials(
         project_id=vertex_project,
@@ -2457,7 +2457,10 @@ def _resolve_alias_to_upstream_model(setup_model: str, llm_router: "Router | Non
     )
     if upstream is None:
         return setup_model
-    _, provider, _, _ = litellm.get_llm_provider(model=upstream)
+    try:
+        _, provider, _, _ = litellm.get_llm_provider(model=upstream)
+    except litellm.exceptions.BadRequestError:
+        return upstream
     return upstream.removeprefix(f"{provider}/")
 
 
diff --git a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
index d68ef8019d2..5608e8b384d 100644
--- a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
+++ b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
@@ -32,7 +32,7 @@ from websockets.exceptions import (
     ConnectionClosedOK,
     InvalidStatus,
 )
-from websockets.frames import Close
+from websockets.frames import EXTERNAL_CLOSE_CODES, Close
 
 import litellm
 from litellm._logging import verbose_proxy_logger
@@ -1930,13 +1930,18 @@ def _truncated_close_reason(reason: str) -> str:
 
 def _upstream_close_to_relay(task_results: Iterable[object]) -> Close | None:
     """
-    The upstream close worth telling the client about: anything other than a plain, reasonless normal close
+    The upstream close worth telling the client about: anything other than a plain, reasonless normal close.
+
+    Codes outside ``EXTERNAL_CLOSE_CODES`` and the private range never travel on the wire (1006 for a socket that
+    died without a close frame, 1005 for one that sent no code), so relaying them would build an invalid frame
     """
     upstream_close: Final = next((result for result in task_results if isinstance(result, Close)), None)
     if upstream_close is None:
         return None
     if upstream_close.code == 1000 and upstream_close.reason == "":
         return None
+    if upstream_close.code not in EXTERNAL_CLOSE_CODES and not 3000 <= upstream_close.code < 5000:
+        return None
     return upstream_close
 
 
diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
index 844aa099541..2663396bf53 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
@@ -5188,6 +5188,49 @@ async def test_websocket_passthrough_rewrites_gateway_alias_setup_model():
     assert sent_setup["model"] == "projects/proj-db/locations/global/publishers/google/models/gemini-live-2.5-flash"
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("rcvd_close", [None, "abnormal", "no_status"])
+async def test_websocket_passthrough_does_not_relay_unsendable_upstream_close(rcvd_close):
+    from websockets.exceptions import ConnectionClosedError
+    from websockets.frames import Close
+
+    rcvd = {
+        None: None,
+        "abnormal": Close(1006, "connection died"),
+        "no_status": Close(1005, ""),
+    }[rcvd_close]
+    upstream_ws = ClosingUpstreamWebSocket(
+        ConnectionClosedError(rcvd=rcvd, sent=None, rcvd_then_sent=None)
+    )
+    websocket = _client_websocket(_pending_receive)
+
+    with _patched_websocket_passthrough_environment(upstream_ws):
+        await websocket_passthrough_request(
+            websocket=websocket,
+            target="wss://aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent",
+            custom_headers={"Authorization": "Bearer token"},
+            user_api_key_dict=UserAPIKeyAuth(),
+            forward_headers=False,
+            endpoint="/vertex_ai/live",
+            accept_websocket=False,
+        )
+
+    websocket.close.assert_awaited_once_with()
+
+
+@pytest.mark.asyncio
+async def test_websocket_passthrough_rewrites_alias_of_unrecognised_upstream_model():
+    llm_router = MagicMock()
+    llm_router.get_model_list.return_value = [
+        {"model_name": "gemini-live", "litellm_params": {"model": "self-hosted-live-endpoint"}}
+    ]
+
+    sent_frame = await _run_setup_rewrite_passthrough("gemini-live", llm_router=llm_router)
+
+    sent_setup = json.loads(sent_frame)["setup"]
+    assert sent_setup["model"] == "projects/proj-db/locations/global/publishers/google/models/self-hosted-live-endpoint"
+
+
 @pytest.mark.asyncio
 async def test_websocket_passthrough_leaves_full_resource_setup_model_untouched():
     full_resource = "projects/other/locations/us-central1/publishers/google/models/gemini-2.0-flash-live-preview-04-09"

From d434787a20e5e170bf94cfb89393c691f1ad0054 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 02:19:38 -0700
Subject: [PATCH 07/35] fix: refuse to guess a vertex project when live
 passthrough has no model hint

---
 .../passthrough_endpoint_router.py            | 17 ++++++++++---
 .../test_passthrough_endpoint_router.py       | 25 +++++++++++++++----
 2 files changed, 33 insertions(+), 9 deletions(-)

diff --git a/litellm/proxy/pass_through_endpoints/passthrough_endpoint_router.py b/litellm/proxy/pass_through_endpoints/passthrough_endpoint_router.py
index e7887e33ca6..28067c842cd 100644
--- a/litellm/proxy/pass_through_endpoints/passthrough_endpoint_router.py
+++ b/litellm/proxy/pass_through_endpoints/passthrough_endpoint_router.py
@@ -126,6 +126,9 @@ class PassthroughEndpointRouter:
 
         ``deployment_key_to_vertex_credentials`` is only reachable when the caller names a project and location,
         which WebSocket clients never do, so DB-stored deployments need this lookup to be usable at all.
+
+        With no model to go on, only deployments that agree on a project and location answer: guessing between
+        two Vertex projects would mint a token for one and later send the other one's model name
         """
         llm_router: Final = self.llm_router_getter()
         if llm_router is None:
@@ -135,16 +138,22 @@ class PassthroughEndpointRouter:
             for deployment in (llm_router.get_model_list() or ())
             if (credentials := self._resolve_vertex_deployment_credentials(deployment["litellm_params"])) is not None
         )
-        if len(resolved) == 0:
-            return None
-        return next(
+        matched: Final = next(
             (
                 credentials
                 for deployment, credentials in resolved
                 if model is not None and self._deployment_matches_model(deployment, model)
             ),
-            resolved[0][1],
+            None,
         )
+        if matched is not None:
+            return matched
+        targets: Final = frozenset(
+            (credentials.vertex_project, credentials.vertex_location) for _, credentials in resolved
+        )
+        if len(targets) != 1:
+            return None
+        return resolved[0][1]
 
     def _resolve_vertex_deployment_credentials(
         self, litellm_params: LiteLLMParamsTypedDict
diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_endpoint_router.py b/tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_endpoint_router.py
index 7816178471f..f86bfb8bb1b 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_endpoint_router.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_endpoint_router.py
@@ -268,14 +268,29 @@ def test_vertex_model_hint_prefers_matching_deployment():
     assert by_upstream_id is not None and by_upstream_id.vertex_project == "proj-live"
 
 
-def test_vertex_unmatched_hint_falls_back_to_first_flagged_deployment():
+def test_vertex_without_usable_hint_refuses_to_guess_between_projects():
     passthrough_router = _passthrough_router(_two_vertex_deployments_router())
 
-    unmatched = passthrough_router.get_vertex_credentials_from_router_deployments(model="unknown-model")
-    no_hint = passthrough_router.get_vertex_credentials_from_router_deployments(model=None)
+    assert passthrough_router.get_vertex_credentials_from_router_deployments(model="unknown-model") is None
+    assert passthrough_router.get_vertex_credentials_from_router_deployments(model=None) is None
 
-    assert unmatched is not None and unmatched.vertex_project == "proj-first"
-    assert no_hint is not None and no_hint.vertex_project == "proj-first"
+
+def test_vertex_without_hint_falls_back_when_deployments_share_a_target():
+    llm_router = litellm.Router(
+        model_list=[
+            _vertex_deployment(
+                "gemini-flash", "vertex_ai/gemini-2.5-flash", vertex_project="proj-one", vertex_location="global"
+            ),
+            _vertex_deployment(
+                "gemini-live", "vertex_ai/gemini-live-2.5-flash", vertex_project="proj-one", vertex_location="global"
+            ),
+        ]
+    )
+    passthrough_router = _passthrough_router(llm_router)
+
+    resolved = passthrough_router.get_vertex_credentials_from_router_deployments(model=None)
+
+    assert resolved is not None and resolved.vertex_project == "proj-one"
 
 
 def test_no_flagged_vertex_deployment_returns_none():

From 58844d3bda3c74ba35c3a571de0a8d2fcf2b6a79 Mon Sep 17 00:00:00 2001
From: mateo-berri <edgetonmas@gmail.com>
Date: Thu, 20 Aug 2026 02:36:47 -0700
Subject: [PATCH 08/35] refactor(realtime): inject the vertex access token
 resolver

Take the resolver and its timeout as parameters of the bounded helper and
bind the vertex one once at module level, so the timeout tests drive an
injected fake instead of patching a shared singleton.
---
 litellm/realtime_api/main.py                 | 15 ++-
 litellm/types/llms/vertex_ai.py              | 13 ++-
 tests/test_litellm/realtime_api/test_main.py | 99 +++++++++++++-------
 3 files changed, 86 insertions(+), 41 deletions(-)

diff --git a/litellm/realtime_api/main.py b/litellm/realtime_api/main.py
index 8fde7cb75c5..56b3931711e 100644
--- a/litellm/realtime_api/main.py
+++ b/litellm/realtime_api/main.py
@@ -15,7 +15,7 @@ from litellm.llms.base_llm.realtime.transformation import BaseRealtimeConfig
 from litellm.llms.custom_httpx.llm_http_handler import BaseLLMHTTPHandler
 from litellm.llms.xai.common_utils import XAIModelInfo
 from litellm.secret_managers.main import get_secret_str
-from litellm.types.llms.vertex_ai import VERTEX_CREDENTIALS_TYPES
+from litellm.types.llms.vertex_ai import VERTEX_CREDENTIALS_TYPES, VertexAccessTokenResolver
 from litellm.types.realtime import (
     RealtimeClientSecretRequest,
     RealtimeExpiresAfter,
@@ -43,6 +43,7 @@ openai_realtime: Final = OpenAIRealtime()
 bedrock_realtime: Final = BedrockRealtime()
 xai_realtime: Final = XAIRealtime()
 vertex_llm_base: Final = VertexBase()
+vertex_access_token_resolver: Final[VertexAccessTokenResolver] = vertex_llm_base._ensure_access_token_async
 base_llm_http_handler = BaseLLMHTTPHandler()
 
 
@@ -290,20 +291,22 @@ async def arealtime_calls(
 async def _resolve_vertex_access_token_bounded(
     credentials: VERTEX_CREDENTIALS_TYPES | None,
     project_id: str | None,
+    resolver: VertexAccessTokenResolver,
+    timeout_seconds: float,
 ) -> tuple[str, str]:
     try:
         return await asyncio.wait_for(
-            vertex_llm_base._ensure_access_token_async(
+            resolver(
                 credentials=credentials,
                 project_id=project_id,
                 custom_llm_provider="vertex_ai",
             ),
-            timeout=REALTIME_CREDENTIAL_RESOLUTION_TIMEOUT_SECONDS,
+            timeout=timeout_seconds,
         )
     except asyncio.TimeoutError as e:
         raise ValueError(
             "Vertex AI realtime: timed out fetching Google OAuth access token after "
-            f"{REALTIME_CREDENTIAL_RESOLUTION_TIMEOUT_SECONDS}s; check network egress from the proxy "
+            f"{timeout_seconds}s; check network egress from the proxy "
             "to the OAuth token endpoint (oauth2.googleapis.com)"
         ) from e
 
@@ -508,6 +511,8 @@ async def _arealtime(
         ) = await _resolve_vertex_access_token_bounded(
             credentials=vertex_credentials,
             project_id=vertex_project,
+            resolver=vertex_access_token_resolver,
+            timeout_seconds=REALTIME_CREDENTIAL_RESOLUTION_TIMEOUT_SECONDS,
         )
 
         vertex_realtime_config: Final = VertexAIRealtimeConfig(
@@ -588,6 +593,8 @@ async def _realtime_health_check(
         ) = await _resolve_vertex_access_token_bounded(
             credentials=VertexBase.safe_get_vertex_ai_credentials(vertex_model_params),
             project_id=VertexBase.safe_get_vertex_ai_project(vertex_model_params),
+            resolver=vertex_access_token_resolver,
+            timeout_seconds=REALTIME_CREDENTIAL_RESOLUTION_TIMEOUT_SECONDS,
         )
         vertex_realtime_config: Final = VertexAIRealtimeConfig(
             access_token=access_token,
diff --git a/litellm/types/llms/vertex_ai.py b/litellm/types/llms/vertex_ai.py
index b750563432e..3b95b786631 100644
--- a/litellm/types/llms/vertex_ai.py
+++ b/litellm/types/llms/vertex_ai.py
@@ -1,5 +1,5 @@
 from enum import Enum
-from typing import Any, Final, Literal
+from typing import Any, Final, Literal, Protocol
 
 from typing_extensions import (
     Required,
@@ -747,6 +747,17 @@ class VertexVideoGenerationResponse(TypedDict, total=False):
 VERTEX_CREDENTIALS_TYPES = str | dict[str, str]
 
 
+class VertexAccessTokenResolver(Protocol):
+    """Resolves a Google OAuth access token and the project id it belongs to."""
+
+    async def __call__(
+        self,
+        credentials: VERTEX_CREDENTIALS_TYPES | None,
+        project_id: str | None,
+        custom_llm_provider: Literal["vertex_ai", "vertex_ai_beta", "gemini"],
+    ) -> tuple[str, str]: ...
+
+
 class VertexPartnerProvider(str, Enum):
     mistralai = "mistralai"
     llama = "llama"
diff --git a/tests/test_litellm/realtime_api/test_main.py b/tests/test_litellm/realtime_api/test_main.py
index 8ed7fb06e84..9f48d4d427b 100644
--- a/tests/test_litellm/realtime_api/test_main.py
+++ b/tests/test_litellm/realtime_api/test_main.py
@@ -93,12 +93,70 @@ def test_client_secret_session_model_takes_priority_over_top_level(monkeypatch):
     assert captured["request_data"]["session"]["model"] == "gpt-realtime-session"
 
 
+async def _hanging_resolver(credentials, project_id, custom_llm_provider) -> tuple[str, str]:
+    await asyncio.sleep(30)
+    return "", ""
+
+
+async def _thread_offloaded_hanging_resolver(credentials, project_id, custom_llm_provider) -> tuple[str, str]:
+    from litellm.litellm_core_utils.asyncify import asyncify
+
+    await asyncify(time.sleep)(30)
+    return "", ""
+
+
+async def _instant_resolver(credentials, project_id, custom_llm_provider) -> tuple[str, str]:
+    return "token-abc", "resolved-project"
+
+
 @pytest.mark.asyncio
-async def test_arealtime_vertex_hung_credential_resolution_raises_promptly(monkeypatch):
+async def test_vertex_credential_resolution_returns_the_resolved_token_and_project():
+    assert await realtime_main._resolve_vertex_access_token_bounded(
+        credentials="fake-credentials",
+        project_id="fake-project",
+        resolver=_instant_resolver,
+        timeout_seconds=5,
+    ) == ("token-abc", "resolved-project")
+
+
+@pytest.mark.asyncio
+async def test_vertex_credential_resolution_times_out_instead_of_hanging():
     """Regression for the realtime accept-then-silence hang: a stalled Google
-    OAuth token refresh used to block _arealtime's vertex branch unbounded
-    (minutes of zero frames for the client). It must instead raise a clear,
-    prompt error naming the credential-resolution timeout."""
+    OAuth token refresh used to block the vertex branch unbounded (minutes of
+    zero frames for the client). It must raise promptly and name the timeout."""
+    start = time.monotonic()
+    with pytest.raises(ValueError, match="timed out fetching Google OAuth access token"):
+        await realtime_main._resolve_vertex_access_token_bounded(
+            credentials="fake-credentials",
+            project_id="fake-project",
+            resolver=_hanging_resolver,
+            timeout_seconds=0.05,
+        )
+    assert time.monotonic() - start < 5
+
+
+@pytest.mark.asyncio
+async def test_vertex_credential_resolution_bounds_a_thread_offloaded_refresh():
+    """The real stall is a blocking google-auth refresh that runs in a worker
+    thread via asyncify, not a plain awaitable sleep. A timeout that only bounds
+    cancellable awaits would leave that shape hanging, so bound the shape the
+    proxy actually runs."""
+    start = time.monotonic()
+    with pytest.raises(ValueError, match="timed out fetching Google OAuth access token"):
+        await realtime_main._resolve_vertex_access_token_bounded(
+            credentials="fake-credentials",
+            project_id="fake-project",
+            resolver=_thread_offloaded_hanging_resolver,
+            timeout_seconds=0.05,
+        )
+    assert time.monotonic() - start < 5
+
+
+@pytest.mark.asyncio
+async def test_arealtime_vertex_branch_resolves_credentials_under_a_bound(monkeypatch):
+    """The wiring half of the regression: the vertex branch of _arealtime must
+    go through the bounded resolver, so a hung token refresh surfaces as a
+    prompt error there rather than as an accepted-then-silent websocket."""
 
     async def hanging_token_refresh(**kwargs):
         await asyncio.sleep(30)
@@ -107,38 +165,7 @@ async def test_arealtime_vertex_hung_credential_resolution_raises_promptly(monke
         return model, "vertex_ai", None, api_base
 
     monkeypatch.setattr(realtime_main, "get_llm_provider", mock_get_llm_provider)
-    monkeypatch.setattr(realtime_main.vertex_llm_base, "_ensure_access_token_async", hanging_token_refresh)
-    monkeypatch.setattr(realtime_main, "REALTIME_CREDENTIAL_RESOLUTION_TIMEOUT_SECONDS", 0.05)
-
-    start = time.monotonic()
-    with pytest.raises(ValueError, match="timed out fetching Google OAuth access token"):
-        await realtime_main._arealtime.__wrapped__(
-            model="gemini-live-2.5-flash",
-            websocket=MagicMock(),
-            litellm_logging_obj=FakeLogging(),
-            vertex_credentials="fake-credentials",
-            vertex_project="fake-project",
-            vertex_location="us-central1",
-        )
-    assert time.monotonic() - start < 5
-
-
-@pytest.mark.asyncio
-async def test_arealtime_vertex_credential_timeout_survives_thread_offloaded_refresh(monkeypatch):
-    """The real stall is a blocking google-auth refresh that runs in a worker
-    thread via asyncify, not a plain awaitable sleep. A timeout that only bounds
-    cancellable awaits would leave that shape hanging, so bound the shape the
-    proxy actually runs."""
-    from litellm.litellm_core_utils.asyncify import asyncify
-
-    async def thread_offloaded_hanging_refresh(**kwargs):
-        return await asyncify(time.sleep)(30)
-
-    def mock_get_llm_provider(model, api_base, api_key):
-        return model, "vertex_ai", None, api_base
-
-    monkeypatch.setattr(realtime_main, "get_llm_provider", mock_get_llm_provider)
-    monkeypatch.setattr(realtime_main.vertex_llm_base, "_ensure_access_token_async", thread_offloaded_hanging_refresh)
+    monkeypatch.setattr(realtime_main, "vertex_access_token_resolver", hanging_token_refresh)
     monkeypatch.setattr(realtime_main, "REALTIME_CREDENTIAL_RESOLUTION_TIMEOUT_SECONDS", 0.05)
 
     start = time.monotonic()

From d643136895d6d3c00f2339b75e63162098bc0802 Mon Sep 17 00:00:00 2001
From: Mateo <edgetonmas@gmail.com>
Date: Thu, 20 Aug 2026 02:49:01 -0700
Subject: [PATCH 09/35] fix(realtime): resolve the vertex token resolver at
 call time

Binding the bound method at import froze the module-level VertexBase
instance, so callers that swap it no longer reached their replacement.
---
 litellm/realtime_api/main.py | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/litellm/realtime_api/main.py b/litellm/realtime_api/main.py
index 56b3931711e..4e02be36daa 100644
--- a/litellm/realtime_api/main.py
+++ b/litellm/realtime_api/main.py
@@ -2,7 +2,7 @@
 
 import asyncio
 import os
-from typing import Any, Final, cast
+from typing import Any, Final, Literal, cast
 
 import litellm
 from litellm.constants import (
@@ -43,7 +43,6 @@ openai_realtime: Final = OpenAIRealtime()
 bedrock_realtime: Final = BedrockRealtime()
 xai_realtime: Final = XAIRealtime()
 vertex_llm_base: Final = VertexBase()
-vertex_access_token_resolver: Final[VertexAccessTokenResolver] = vertex_llm_base._ensure_access_token_async
 base_llm_http_handler = BaseLLMHTTPHandler()
 
 
@@ -288,6 +287,18 @@ async def arealtime_calls(
     )
 
 
+async def vertex_access_token_resolver(
+    credentials: VERTEX_CREDENTIALS_TYPES | None,
+    project_id: str | None,
+    custom_llm_provider: Literal["vertex_ai", "vertex_ai_beta", "gemini"],
+) -> tuple[str, str]:
+    return await vertex_llm_base._ensure_access_token_async(
+        credentials=credentials,
+        project_id=project_id,
+        custom_llm_provider=custom_llm_provider,
+    )
+
+
 async def _resolve_vertex_access_token_bounded(
     credentials: VERTEX_CREDENTIALS_TYPES | None,
     project_id: str | None,

From 4f04e59ca036860ed1a83eb6169b4bdd20b31bb1 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 03:05:48 -0700
Subject: [PATCH 10/35] fix: harden vertex live passthrough against client
 model forms and dict credentials

- accept the Live SDK's models/<id> and LiteLLM's vertex_ai/<id> when rewriting the setup model
- keep a dict service account intact instead of stringifying it
- treat same-target deployments holding different credentials as ambiguous
- guard both websocket states before every close so a second close cannot raise
- build the sendable close codes from the public CloseCode enum
---
 .../llm_passthrough_endpoints.py              |  40 +++++--
 .../pass_through_endpoints.py                 |  32 ++++--
 .../passthrough_endpoint_router.py            |  28 ++++-
 .../test_llm_pass_through_endpoints.py        | 107 ++++++++++++++++++
 .../test_pass_through_endpoints.py            |  32 ++++++
 .../test_passthrough_endpoint_router.py       |  53 +++++++++
 6 files changed, 266 insertions(+), 26 deletions(-)

diff --git a/litellm/proxy/pass_through_endpoints/llm_passthrough_endpoints.py b/litellm/proxy/pass_through_endpoints/llm_passthrough_endpoints.py
index c2b221b1f7a..7ce41c1d5b6 100644
--- a/litellm/proxy/pass_through_endpoints/llm_passthrough_endpoints.py
+++ b/litellm/proxy/pass_through_endpoints/llm_passthrough_endpoints.py
@@ -2384,6 +2384,21 @@ VERTEX_LIVE_UNCONFIGURED_CLOSE_REASON: Final = (
 
 VERTEX_PUBLISHER_MODEL_PREFIX: Final = "publishers/google/models/"
 
+VERTEX_PUBLISHERS_SEGMENT: Final = "publishers/"
+
+
+def _vertex_publisher_model_suffix(model: str) -> str:
+    """
+    Turn whatever the client named into the ``publishers/<publisher>/models/<id>`` tail of a Vertex resource name.
+
+    Clients send bare ids, LiteLLM ids (``vertex_ai/gemini-live-2.5-flash``), and the Live SDK's ``models/<id>``,
+    and a publisher model id never contains a slash, so anything ahead of the last one is addressing, not identity
+    """
+    publishers_at: Final = model.find(VERTEX_PUBLISHERS_SEGMENT)
+    if publishers_at != -1:
+        return model[publishers_at:]
+    return f"{VERTEX_PUBLISHER_MODEL_PREFIX}{model.rsplit('/', 1)[-1]}"
+
 
 def _get_llm_router() -> "Router | None":
     from litellm.proxy.proxy_server import llm_router
@@ -2397,8 +2412,12 @@ def _resolve_vertex_live_credentials(
     model: str | None,
 ) -> VertexPassThroughCredentials | None:
     """
-    Resolution order: an explicit project/location registration or ``default_vertex_config``, then any DB model
-    entry flagged ``use_in_pass_through``, then the ``DEFAULT_VERTEXAI_*`` env vars
+    Resolution order: an explicit project/location registration, then ``default_vertex_config`` (which the proxy
+    fills from the ``DEFAULT_VERTEXAI_*`` env vars whenever the yaml leaves it out), then any DB model entry
+    flagged ``use_in_pass_through``.
+
+    DB entries come last on purpose: an operator who set a global default already said which project
+    pass-through traffic should bill to, and this route silently ignoring that would be the worse surprise
     """
     keyed: Final = passthrough_endpoint_router.get_vertex_credentials(
         project_id=vertex_project,
@@ -2436,22 +2455,23 @@ def _build_vertex_live_setup_model_rewriter(
         if setup_model.startswith("projects/"):
             return setup_model
         aliased: Final = _resolve_alias_to_upstream_model(setup_model, llm_router)
-        return (
-            f"projects/{vertex_project}/locations/{vertex_location}/"
-            f"{VERTEX_PUBLISHER_MODEL_PREFIX}{aliased.removeprefix(VERTEX_PUBLISHER_MODEL_PREFIX)}"
-        )
+        return f"projects/{vertex_project}/locations/{vertex_location}/{_vertex_publisher_model_suffix(aliased)}"
 
     return rewrite
 
 
 def _resolve_alias_to_upstream_model(setup_model: str, llm_router: "Router | None") -> str:
+    """
+    The Live SDK wraps whatever the caller typed as ``models/<name>``, so a gateway alias arrives prefixed
+    """
     if llm_router is None:
         return setup_model
+    candidates: Final = (setup_model, setup_model.rsplit("/", 1)[-1])
     upstream: Final = next(
         (
-            deployment["litellm_params"]["model"]
+            deployment["litellm_params"].get("model")
             for deployment in (llm_router.get_model_list() or ())
-            if deployment.get("model_name") == setup_model
+            if deployment.get("model_name") in candidates
         ),
         None,
     )
@@ -2500,9 +2520,7 @@ async def vertex_ai_live_websocket_passthrough(
         vertex_credentials_config.vertex_location if vertex_credentials_config is not None else None
     )
     credentials_value: Final = (
-        str(vertex_credentials_config.vertex_credentials)
-        if vertex_credentials_config is not None and vertex_credentials_config.vertex_credentials is not None
-        else None
+        vertex_credentials_config.vertex_credentials if vertex_credentials_config is not None else None
     )
 
     try:
diff --git a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
index 5608e8b384d..d45421489e7 100644
--- a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
+++ b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
@@ -32,7 +32,7 @@ from websockets.exceptions import (
     ConnectionClosedOK,
     InvalidStatus,
 )
-from websockets.frames import EXTERNAL_CLOSE_CODES, Close
+from websockets.frames import Close, CloseCode
 
 import litellm
 from litellm._logging import verbose_proxy_logger
@@ -1928,11 +1928,26 @@ def _truncated_close_reason(reason: str) -> str:
     return encoded[:WEBSOCKET_CLOSE_REASON_MAX_BYTES].decode("utf-8", errors="ignore")
 
 
+SENDABLE_CLOSE_CODES: Final = frozenset(CloseCode) - frozenset(
+    {CloseCode.NO_STATUS_RCVD, CloseCode.ABNORMAL_CLOSURE, CloseCode.TLS_HANDSHAKE}
+)
+
+
+def _client_socket_is_open(websocket: WebSocket) -> bool:
+    """
+    Starlette tracks the two halves separately and raises on a second close, so both have to still be live
+    """
+    return (
+        websocket.client_state != WebSocketState.DISCONNECTED
+        and websocket.application_state != WebSocketState.DISCONNECTED
+    )
+
+
 def _upstream_close_to_relay(task_results: Iterable[object]) -> Close | None:
     """
     The upstream close worth telling the client about: anything other than a plain, reasonless normal close.
 
-    Codes outside ``EXTERNAL_CLOSE_CODES`` and the private range never travel on the wire (1006 for a socket that
+    Codes outside ``SENDABLE_CLOSE_CODES`` and the private range never travel on the wire (1006 for a socket that
     died without a close frame, 1005 for one that sent no code), so relaying them would build an invalid frame
     """
     upstream_close: Final = next((result for result in task_results if isinstance(result, Close)), None)
@@ -1940,7 +1955,7 @@ def _upstream_close_to_relay(task_results: Iterable[object]) -> Close | None:
         return None
     if upstream_close.code == 1000 and upstream_close.reason == "":
         return None
-    if upstream_close.code not in EXTERNAL_CLOSE_CODES and not 3000 <= upstream_close.code < 5000:
+    if upstream_close.code not in SENDABLE_CLOSE_CODES and not 3000 <= upstream_close.code < 5000:
         return None
     return upstream_close
 
@@ -2268,7 +2283,7 @@ async def websocket_passthrough_request(
                     raise exception
 
             upstream_close: Final = _upstream_close_to_relay(task.result() for task in done)
-            if upstream_close is not None and websocket.application_state != WebSocketState.DISCONNECTED:
+            if upstream_close is not None and _client_socket_is_open(websocket):
                 await websocket.close(
                     code=upstream_close.code,
                     reason=_truncated_close_reason(upstream_close.reason),
@@ -2359,7 +2374,7 @@ async def websocket_passthrough_request(
             ),
         )
 
-        if websocket.client_state != WebSocketState.DISCONNECTED:
+        if _client_socket_is_open(websocket):
             await websocket.close(
                 code=getattr(exc, "status_code", 1011),
                 reason="Upstream connection rejected",
@@ -2387,13 +2402,10 @@ async def websocket_passthrough_request(
             ),
         )
 
-        if websocket.client_state != WebSocketState.DISCONNECTED:
+        if _client_socket_is_open(websocket):
             await websocket.close(code=1011, reason="WebSocket passthrough error")
     finally:
-        if (
-            websocket.client_state != WebSocketState.DISCONNECTED
-            and websocket.application_state != WebSocketState.DISCONNECTED
-        ):
+        if _client_socket_is_open(websocket):
             await websocket.close()
 
 
diff --git a/litellm/proxy/pass_through_endpoints/passthrough_endpoint_router.py b/litellm/proxy/pass_through_endpoints/passthrough_endpoint_router.py
index 28067c842cd..7fd607fc4d0 100644
--- a/litellm/proxy/pass_through_endpoints/passthrough_endpoint_router.py
+++ b/litellm/proxy/pass_through_endpoints/passthrough_endpoint_router.py
@@ -1,3 +1,4 @@
+import json
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Final
 
@@ -27,6 +28,15 @@ def _get_str_value(values: dict[str, object] | None, key: str) -> str | None:
     return value if isinstance(value, str) else None
 
 
+def _credential_identity(credentials: VERTEX_CREDENTIALS_TYPES | None) -> str | None:
+    """
+    A hashable stand-in for a credential, so two deployments can be compared for holding the same one
+    """
+    if isinstance(credentials, dict):
+        return json.dumps(credentials, sort_keys=True)
+    return credentials
+
+
 class PassthroughEndpointRouter:
     """
     Use this class to Get credentials for pass-through endpoints
@@ -127,8 +137,8 @@ class PassthroughEndpointRouter:
         ``deployment_key_to_vertex_credentials`` is only reachable when the caller names a project and location,
         which WebSocket clients never do, so DB-stored deployments need this lookup to be usable at all.
 
-        With no model to go on, only deployments that agree on a project and location answer: guessing between
-        two Vertex projects would mint a token for one and later send the other one's model name
+        With no model to go on, only deployments that agree on a project, a location, and a credential answer:
+        guessing between two Vertex projects would mint a token for one and later send the other one's model name
         """
         llm_router: Final = self.llm_router_getter()
         if llm_router is None:
@@ -149,7 +159,12 @@ class PassthroughEndpointRouter:
         if matched is not None:
             return matched
         targets: Final = frozenset(
-            (credentials.vertex_project, credentials.vertex_location) for _, credentials in resolved
+            (
+                credentials.vertex_project,
+                credentials.vertex_location,
+                _credential_identity(credentials.vertex_credentials),
+            )
+            for _, credentials in resolved
         )
         if len(targets) != 1:
             return None
@@ -172,9 +187,12 @@ class PassthroughEndpointRouter:
         vertex_location: Final = _get_str_value(credential_values, "vertex_location") or litellm_params.get(
             "vertex_location"
         )
-        vertex_credentials: Final = _get_str_value(credential_values, "vertex_credentials") or litellm_params.get(
-            "vertex_credentials"
+        stored_credentials: Final = (
+            credential_values.get("vertex_credentials") if credential_values is not None else None
         )
+        vertex_credentials: Final = (
+            stored_credentials if isinstance(stored_credentials, (str, dict)) else None
+        ) or litellm_params.get("vertex_credentials")
         if vertex_project is None or vertex_location is None:
             return None
         return VertexPassThroughCredentials(
diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_llm_pass_through_endpoints.py b/tests/test_litellm/proxy/pass_through_endpoints/test_llm_pass_through_endpoints.py
index 5ed974c7a47..f994fba371b 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_llm_pass_through_endpoints.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_llm_pass_through_endpoints.py
@@ -3889,6 +3889,9 @@ class TestComprehendMedicalProxyRoute:
         assert exc_info.value.status_code == 400
 
 
+LIVE_RESOURCE_PATH = "projects/proj-db/locations/global/publishers/google/models/gemini-live-2.5-flash"
+
+
 class TestVertexAILiveWebsocketPassthrough:
     def _websocket(self):
         from starlette.websockets import WebSocketState
@@ -3959,6 +3962,110 @@ class TestVertexAILiveWebsocketPassthrough:
         )
         websocket.close.assert_not_awaited()
 
+    @pytest.mark.parametrize(
+        "setup_model, expected",
+        [
+            ("gemini-live-2.5-flash", LIVE_RESOURCE_PATH),
+            ("models/gemini-live-2.5-flash", LIVE_RESOURCE_PATH),
+            ("vertex_ai/gemini-live-2.5-flash", LIVE_RESOURCE_PATH),
+            ("gemini-live", LIVE_RESOURCE_PATH),
+            ("models/gemini-live", LIVE_RESOURCE_PATH),
+            (
+                "publishers/meta/models/llama-3.3-70b-instruct-maas",
+                "projects/proj-db/locations/global/publishers/meta/models/llama-3.3-70b-instruct-maas",
+            ),
+            (
+                "projects/other/locations/us-central1/publishers/google/models/gemini-2.0-flash",
+                "projects/other/locations/us-central1/publishers/google/models/gemini-2.0-flash",
+            ),
+        ],
+    )
+    def test_setup_model_rewriter_normalises_the_forms_clients_send(self, setup_model, expected):
+        from litellm.proxy.pass_through_endpoints import (
+            llm_passthrough_endpoints as passthrough_module,
+        )
+
+        llm_router = litellm.Router(
+            model_list=[
+                {
+                    "model_name": "gemini-live",
+                    "litellm_params": {
+                        "model": "vertex_ai/gemini-live-2.5-flash",
+                        "use_in_pass_through": True,
+                        "vertex_project": "proj-db",
+                        "vertex_location": "global",
+                    },
+                }
+            ]
+        )
+
+        rewriter = passthrough_module._build_vertex_live_setup_model_rewriter(
+            vertex_project="proj-db",
+            vertex_location="global",
+            llm_router=llm_router,
+        )
+
+        assert rewriter is not None
+        assert rewriter(setup_model) == expected
+
+    @pytest.mark.asyncio
+    async def test_default_vertex_config_outranks_db_deployment(self, monkeypatch):
+        from litellm.proxy.pass_through_endpoints import (
+            llm_passthrough_endpoints as passthrough_module,
+        )
+        from litellm.types.passthrough_endpoints.vertex_ai import (
+            VertexPassThroughCredentials,
+        )
+
+        llm_router = litellm.Router(
+            model_list=[
+                {
+                    "model_name": "gemini-live",
+                    "litellm_params": {
+                        "model": "vertex_ai/gemini-live-2.5-flash",
+                        "use_in_pass_through": True,
+                        "vertex_project": "proj-db",
+                        "vertex_location": "global",
+                        "vertex_credentials": '{"type": "db_account"}',
+                    },
+                }
+            ]
+        )
+        monkeypatch.setattr("litellm.proxy.proxy_server.llm_router", llm_router)
+        monkeypatch.setattr(
+            passthrough_module.passthrough_endpoint_router,
+            "default_vertex_config",
+            VertexPassThroughCredentials(
+                vertex_project="proj-env",
+                vertex_location="global",
+                vertex_credentials='{"type": "env_account"}',
+            ),
+        )
+        self._clear_vertex_env(monkeypatch)
+        websocket = self._websocket()
+        ensure_token = AsyncMock(return_value=("token-abc", "proj-env"))
+        ws_passthrough = AsyncMock()
+
+        with (
+            patch.object(passthrough_module.vertex_llm_base, "_ensure_access_token_async", ensure_token),
+            patch.object(passthrough_module, "websocket_passthrough_request", ws_passthrough),
+        ):
+            await passthrough_module.vertex_ai_live_websocket_passthrough(
+                websocket=websocket,
+                model="gemini-live",
+                user_api_key_dict=UserAPIKeyAuth(),
+            )
+
+        ensure_token.assert_awaited_once_with(
+            credentials='{"type": "env_account"}',
+            project_id="proj-env",
+            custom_llm_provider="vertex_ai_beta",
+        )
+        rewriter = ws_passthrough.await_args.kwargs["setup_model_rewriter"]
+        assert rewriter("gemini-live") == (
+            "projects/proj-env/locations/global/publishers/google/models/gemini-live-2.5-flash"
+        )
+
     @pytest.mark.asyncio
     async def test_credential_failure_close_names_configuration_options(self, monkeypatch):
         from litellm.proxy.pass_through_endpoints import (
diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
index 2663396bf53..00097166c13 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
@@ -5243,6 +5243,38 @@ async def test_websocket_passthrough_leaves_full_resource_setup_model_untouched(
     )
 
 
+@pytest.mark.asyncio
+async def test_websocket_passthrough_does_not_close_twice_when_success_logging_fails():
+    from websockets.exceptions import ConnectionClosedError
+    from websockets.frames import Close
+
+    upstream_reason = "Publisher Model `projects/p/locations/global/publishers/google/models/nope` was not found"
+    upstream_ws = ClosingUpstreamWebSocket(
+        ConnectionClosedError(rcvd=Close(1008, upstream_reason), sent=Close(1008, ""), rcvd_then_sent=True)
+    )
+    websocket = _client_websocket(_pending_receive)
+
+    with (
+        _patched_websocket_passthrough_environment(upstream_ws),
+        patch(
+            "litellm.proxy.pass_through_endpoints.pass_through_endpoints."
+            "GLOBAL_LOGGING_WORKER.ensure_initialized_and_enqueue",
+            side_effect=RuntimeError("logging worker down"),
+        ),
+    ):
+        await websocket_passthrough_request(
+            websocket=websocket,
+            target="wss://aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent",
+            custom_headers={"Authorization": "Bearer token"},
+            user_api_key_dict=UserAPIKeyAuth(),
+            forward_headers=False,
+            endpoint="/vertex_ai/live",
+            accept_websocket=False,
+        )
+
+    websocket.close.assert_awaited_once_with(code=1008, reason=upstream_reason)
+
+
 def _passthrough_kwargs_for_reservation(
     user_api_key_dict: UserAPIKeyAuth, parsed_body: Optional[dict] = None
 ) -> dict:
diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_endpoint_router.py b/tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_endpoint_router.py
index f86bfb8bb1b..e3cbc2d507f 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_endpoint_router.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_passthrough_endpoint_router.py
@@ -293,6 +293,59 @@ def test_vertex_without_hint_falls_back_when_deployments_share_a_target():
     assert resolved is not None and resolved.vertex_project == "proj-one"
 
 
+def test_vertex_without_hint_refuses_to_guess_between_service_accounts():
+    llm_router = litellm.Router(
+        model_list=[
+            _vertex_deployment(
+                "gemini-flash",
+                "vertex_ai/gemini-2.5-flash",
+                vertex_project="proj-one",
+                vertex_location="global",
+                vertex_credentials='{"client_email": "flash@proj-one.iam"}',
+            ),
+            _vertex_deployment(
+                "gemini-live",
+                "vertex_ai/gemini-live-2.5-flash",
+                vertex_project="proj-one",
+                vertex_location="global",
+                vertex_credentials='{"client_email": "live@proj-one.iam"}',
+            ),
+        ]
+    )
+    passthrough_router = _passthrough_router(llm_router)
+
+    assert passthrough_router.get_vertex_credentials_from_router_deployments(model=None) is None
+
+
+def test_vertex_named_credential_keeps_dict_service_account():
+    service_account = {"type": "service_account", "client_email": "live@proj-db.iam"}
+    CredentialAccessor.upsert_credentials(
+        [
+            _vertex_credential(
+                "cred_gcp_dict",
+                {
+                    "vertex_project": "proj-db",
+                    "vertex_location": "global",
+                    "vertex_credentials": service_account,
+                },
+            )
+        ]
+    )
+    llm_router = litellm.Router(
+        model_list=[
+            _vertex_deployment(
+                "gemini-live", "vertex_ai/gemini-live-2.5-flash", litellm_credential_name="cred_gcp_dict"
+            )
+        ]
+    )
+    passthrough_router = _passthrough_router(llm_router)
+
+    resolved = passthrough_router.get_vertex_credentials_from_router_deployments(model=None)
+
+    assert resolved is not None
+    assert resolved.vertex_credentials == service_account
+
+
 def test_no_flagged_vertex_deployment_returns_none():
     llm_router = litellm.Router(
         model_list=[

From cc2013e9660ab722fab9f8097497a121336a034f Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 03:55:25 -0700
Subject: [PATCH 11/35] fix(anthropic): map metadata.user_id to
 prompt_cache_key on the /v1/messages bridge

Both /v1/messages bridges (Responses API adapter for openai/* and the
chat-completions adapter) now derive prompt_cache_key from the first 64
characters of metadata.user_id, next to the existing user mapping. The
chat bridge only sets it when the resolved provider advertises
prompt_cache_key in its supported params, so providers that reject
unknown params are unaffected. A prompt_cache_key sent explicitly by the
client always wins over the derived value.

Fixes #37508
---
 .../adapters/handler.py                       | 10 ++-
 .../adapters/transformation.py                | 31 +++++++-
 .../responses_adapters/handler.py             |  7 +-
 .../responses_adapters/transformation.py      |  6 +-
 .../experimental_pass_through/utils.py        |  9 +++
 litellm/types/llms/openai.py                  |  1 +
 ...al_pass_through_adapters_transformation.py | 79 +++++++++++++++++++
 .../adapters/test_handler_prompt_cache_key.py | 64 +++++++++++++++
 .../test_responses_adapters_handler.py        | 45 +++++++++++
 .../test_responses_adapters_transformation.py | 24 ++++++
 10 files changed, 270 insertions(+), 6 deletions(-)
 create mode 100644 tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_handler_prompt_cache_key.py
 create mode 100644 tests/test_litellm/llms/anthropic/experimental_pass_through/responses_adapters/test_responses_adapters_handler.py

diff --git a/litellm/llms/anthropic/experimental_pass_through/adapters/handler.py b/litellm/llms/anthropic/experimental_pass_through/adapters/handler.py
index 48d8a03d549..89066e33cbc 100644
--- a/litellm/llms/anthropic/experimental_pass_through/adapters/handler.py
+++ b/litellm/llms/anthropic/experimental_pass_through/adapters/handler.py
@@ -484,10 +484,14 @@ class LiteLLMMessagesToCompletionTransformationHandler:
         if "output_config" in extra_kwargs:
             request_data["output_config"] = extra_kwargs["output_config"]
 
+        custom_llm_provider: Final = extra_kwargs.get("custom_llm_provider")
         (
             openai_request,
             tool_name_mapping,
-        ) = ANTHROPIC_ADAPTER.translate_completion_input_params_with_tool_mapping(request_data)
+        ) = ANTHROPIC_ADAPTER.translate_completion_input_params_with_tool_mapping(
+            request_data,
+            custom_llm_provider=custom_llm_provider if isinstance(custom_llm_provider, str) else None,
+        )
 
         if openai_request is None:
             raise ValueError("Failed to translate request to OpenAI format")
@@ -526,6 +530,10 @@ class LiteLLMMessagesToCompletionTransformationHandler:
             if key not in excluded_keys and key not in completion_kwargs and value is not None:
                 completion_kwargs[key] = value
 
+        explicit_prompt_cache_key: Final = extra_kwargs.get("prompt_cache_key")
+        if explicit_prompt_cache_key is not None:
+            completion_kwargs["prompt_cache_key"] = explicit_prompt_cache_key
+
         # Normalize reasoning_effort based on model capabilities
         # (e.g. "max" → "xhigh"/"high", "minimal" → "low" if unsupported)
         # Must run BEFORE _route_openai_thinking, which prepends "responses/"
diff --git a/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py b/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py
index e45414b4a73..5c72fee25a0 100644
--- a/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py
+++ b/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py
@@ -4,8 +4,10 @@ import json
 from collections.abc import AsyncIterator, Iterator, Mapping
 from typing import TYPE_CHECKING, Any, Final, Literal, cast
 
+import litellm
 from litellm.llms.anthropic.experimental_pass_through.utils import (
     is_reasoning_auto_summary_enabled,
+    prompt_cache_key_from_user_id,
 )
 
 # OpenAI has a 64-character limit for function/tool names
@@ -148,7 +150,7 @@ class AnthropicAdapter:
         return result
 
     def translate_completion_input_params_with_tool_mapping(
-        self, kwargs
+        self, kwargs, *, custom_llm_provider: str | None = None
     ) -> tuple[ChatCompletionRequest | None, dict[str, str]]:
         """
         Translate Anthropic request params to OpenAI format, returning tool name mapping.
@@ -179,7 +181,10 @@ class AnthropicAdapter:
         (
             translated_body,
             tool_name_mapping,
-        ) = LiteLLMAnthropicMessagesAdapter().translate_anthropic_to_openai(anthropic_message_request=request_body)
+        ) = LiteLLMAnthropicMessagesAdapter().translate_anthropic_to_openai(
+            anthropic_message_request=request_body,
+            custom_llm_provider=custom_llm_provider,
+        )
 
         return translated_body, tool_name_mapping
 
@@ -907,16 +912,32 @@ class LiteLLMAnthropicMessagesAdapter:
                     ChatCompletionSystemMessage(role="system", content=openai_system_content),
                 )
 
+    @staticmethod
+    def _supports_prompt_cache_key(model: str | None, custom_llm_provider: str | None) -> bool:
+        if not model or not custom_llm_provider:
+            return False
+        supported_params: Final = litellm.get_supported_openai_params(
+            model=model, custom_llm_provider=custom_llm_provider
+        )
+        return "prompt_cache_key" in (supported_params or ())
+
     def _translate_metadata_to_openai(
         self,
         anthropic_message_request: AnthropicMessagesRequest,
         new_kwargs: ChatCompletionRequest,
+        *,
+        custom_llm_provider: str | None = None,
     ) -> None:
         """Translate metadata fields from Anthropic request to OpenAI request."""
         if "metadata" in anthropic_message_request:
             metadata: Final = anthropic_message_request["metadata"]
             if metadata and "user_id" in metadata:
                 new_kwargs["user"] = metadata["user_id"]
+                prompt_cache_key: Final = prompt_cache_key_from_user_id(metadata["user_id"])
+                if prompt_cache_key is not None and self._supports_prompt_cache_key(
+                    anthropic_message_request.get("model"), custom_llm_provider
+                ):
+                    new_kwargs["prompt_cache_key"] = prompt_cache_key
 
         if "litellm_metadata" in anthropic_message_request:
             # metadata will be passed to litellm.acompletion(), it's a litellm_param
@@ -1069,7 +1090,10 @@ class LiteLLMAnthropicMessagesAdapter:
                 new_kwargs[k] = v
 
     def translate_anthropic_to_openai(
-        self, anthropic_message_request: AnthropicMessagesRequest
+        self,
+        anthropic_message_request: AnthropicMessagesRequest,
+        *,
+        custom_llm_provider: str | None = None,
     ) -> tuple[ChatCompletionRequest, dict[str, str]]:
         """
         This is used by the beta Anthropic Adapter, for translating anthropic `/v1/messages` requests to the openai format.
@@ -1103,6 +1127,7 @@ class LiteLLMAnthropicMessagesAdapter:
         self._translate_metadata_to_openai(
             anthropic_message_request=anthropic_message_request,
             new_kwargs=new_kwargs,
+            custom_llm_provider=custom_llm_provider,
         )
         ## CONVERT TOOL CHOICE
         self._translate_tool_choice_to_openai(
diff --git a/litellm/llms/anthropic/experimental_pass_through/responses_adapters/handler.py b/litellm/llms/anthropic/experimental_pass_through/responses_adapters/handler.py
index e6d8686b466..843cda249c5 100644
--- a/litellm/llms/anthropic/experimental_pass_through/responses_adapters/handler.py
+++ b/litellm/llms/anthropic/experimental_pass_through/responses_adapters/handler.py
@@ -105,7 +105,8 @@ def _build_responses_kwargs(
 
     # Forward litellm-specific kwargs (api_key, api_base, logging obj, etc.)
     excluded: Final = {"anthropic_messages"}
-    for key, value in _forwarded_kwargs(extra_kwargs).items():
+    forwarded_kwargs: Final = _forwarded_kwargs(extra_kwargs)
+    for key, value in forwarded_kwargs.items():
         if key == "litellm_logging_obj" and value is not None:
             from litellm.litellm_core_utils.litellm_logging import (
                 Logging as LiteLLMLoggingObject,
@@ -121,6 +122,10 @@ def _build_responses_kwargs(
         elif key not in excluded and key not in responses_kwargs and value is not None:
             responses_kwargs[key] = value
 
+    explicit_prompt_cache_key: Final = forwarded_kwargs.get("prompt_cache_key")
+    if explicit_prompt_cache_key is not None:
+        responses_kwargs["prompt_cache_key"] = explicit_prompt_cache_key
+
     return responses_kwargs
 
 
diff --git a/litellm/llms/anthropic/experimental_pass_through/responses_adapters/transformation.py b/litellm/llms/anthropic/experimental_pass_through/responses_adapters/transformation.py
index 21a8cb9501e..9238433151a 100644
--- a/litellm/llms/anthropic/experimental_pass_through/responses_adapters/transformation.py
+++ b/litellm/llms/anthropic/experimental_pass_through/responses_adapters/transformation.py
@@ -18,6 +18,7 @@ from litellm.litellm_core_utils.reasoning_effort_utils import (
 )
 from litellm.llms.anthropic.experimental_pass_through.utils import (
     is_reasoning_auto_summary_enabled,
+    prompt_cache_key_from_user_id,
 )
 from litellm.types.llms.anthropic import (
     AllAnthropicPassThroughMessageValues,
@@ -452,10 +453,13 @@ class LiteLLMAnthropicToResponsesAPIAdapter:
             if openai_cm is not None:
                 responses_kwargs["context_management"] = openai_cm
 
-        # metadata user_id -> user
+        # metadata user_id -> user and prompt_cache_key
         metadata: Final = anthropic_request.get("metadata")
         if isinstance(metadata, dict) and "user_id" in metadata:
             responses_kwargs["user"] = str(metadata["user_id"])[:64]
+            prompt_cache_key: Final = prompt_cache_key_from_user_id(metadata["user_id"])
+            if prompt_cache_key is not None:
+                responses_kwargs["prompt_cache_key"] = prompt_cache_key
 
         return responses_kwargs
 
diff --git a/litellm/llms/anthropic/experimental_pass_through/utils.py b/litellm/llms/anthropic/experimental_pass_through/utils.py
index 46091cd89a2..c5abcf8c04c 100644
--- a/litellm/llms/anthropic/experimental_pass_through/utils.py
+++ b/litellm/llms/anthropic/experimental_pass_through/utils.py
@@ -1,8 +1,17 @@
 import os
+from typing import Final
 
 import litellm
 from litellm.types.utils import ModelInfo
 
+OPENAI_MAX_PROMPT_CACHE_KEY_LENGTH: Final = 64
+
+
+def prompt_cache_key_from_user_id(user_id: object) -> str | None:
+    if user_id is None:
+        return None
+    return str(user_id)[:OPENAI_MAX_PROMPT_CACHE_KEY_LENGTH] or None
+
 
 def is_reasoning_auto_summary_enabled() -> bool:
     """Check whether the default 'summary: detailed' injection is enabled (opt-in)."""
diff --git a/litellm/types/llms/openai.py b/litellm/types/llms/openai.py
index edfc50c99f6..beb6612497c 100644
--- a/litellm/types/llms/openai.py
+++ b/litellm/types/llms/openai.py
@@ -917,6 +917,7 @@ class ChatCompletionRequest(TypedDict, total=False):
     seed: int
     service_tier: str
     safety_identifier: str
+    prompt_cache_key: str  # writable-ok: the /v1/messages adapter assigns it after construction
     stop: str | list[str]
     stream_options: dict
     temperature: float
diff --git a/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_anthropic_experimental_pass_through_adapters_transformation.py b/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_anthropic_experimental_pass_through_adapters_transformation.py
index 1185893d428..dd1e8a93280 100644
--- a/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_anthropic_experimental_pass_through_adapters_transformation.py
+++ b/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_anthropic_experimental_pass_through_adapters_transformation.py
@@ -635,6 +635,85 @@ def test_translate_anthropic_to_openai_orders_top_level_and_midturn_system():
     ]
 
 
+def _translate_with_metadata(
+    model: str, metadata: dict[str, Any], custom_llm_provider: str | None
+) -> dict[str, Any]:
+    openai_request, _ = LiteLLMAnthropicMessagesAdapter().translate_anthropic_to_openai(
+        anthropic_message_request={
+            "model": model,
+            "max_tokens": 100,
+            "metadata": metadata,
+            "messages": [{"role": "user", "content": "hi"}],
+        },
+        custom_llm_provider=custom_llm_provider,
+    )
+    return cast(dict[str, Any], openai_request)
+
+
+def test_translate_anthropic_to_openai_maps_user_id_to_prompt_cache_key_for_openai():
+    openai_request = _translate_with_metadata("openai/gpt-5.6-luna", {"user_id": "session-abc"}, "openai")
+    assert openai_request["user"] == "session-abc"
+    assert openai_request["prompt_cache_key"] == "session-abc"
+
+
+def test_translate_anthropic_to_openai_truncates_prompt_cache_key_but_keeps_full_user():
+    long_id = "".join(str(i % 10) for i in range(100))
+    openai_request = _translate_with_metadata("openai/gpt-5.6-luna", {"user_id": long_id}, "openai")
+    assert openai_request["user"] == long_id
+    assert openai_request["prompt_cache_key"] == long_id[:64]
+    assert len(openai_request["prompt_cache_key"]) == 64
+
+
+@pytest.mark.parametrize("model", ["azure/my-gpt-5-deployment", "my-gpt-5-deployment"])
+def test_translate_anthropic_to_openai_sets_prompt_cache_key_for_azure(model: str):
+    openai_request = _translate_with_metadata(model, {"user_id": "session-abc"}, "azure")
+    assert openai_request["prompt_cache_key"] == "session-abc"
+
+
+@pytest.mark.parametrize(
+    "model, custom_llm_provider",
+    [
+        ("gemini/gemini-2.5-pro", "gemini"),
+        ("vertex_ai/gemini-2.5-pro", "vertex_ai"),
+        ("anthropic/claude-sonnet-4-5", "anthropic"),
+        ("bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0", "bedrock"),
+        ("no-such-model-lit5875", "no-such-provider-lit5875"),
+    ],
+)
+def test_translate_anthropic_to_openai_skips_prompt_cache_key_when_provider_lacks_it(
+    model: str, custom_llm_provider: str
+):
+    openai_request = _translate_with_metadata(model, {"user_id": "session-abc"}, custom_llm_provider)
+    assert openai_request["user"] == "session-abc"
+    assert "prompt_cache_key" not in openai_request
+
+
+def test_translate_anthropic_to_openai_skips_prompt_cache_key_without_provider():
+    openai_request = _translate_with_metadata("openai/gpt-5.6-luna", {"user_id": "session-abc"}, None)
+    assert openai_request["user"] == "session-abc"
+    assert "prompt_cache_key" not in openai_request
+
+
+@pytest.mark.parametrize("user_id", ["", None])
+def test_translate_anthropic_to_openai_skips_prompt_cache_key_for_empty_or_null_user_id(user_id: str | None):
+    openai_request = _translate_with_metadata("openai/gpt-5.6-luna", {"user_id": user_id}, "openai")
+    assert openai_request["user"] == user_id
+    assert "prompt_cache_key" not in openai_request
+
+
+def test_translate_anthropic_to_openai_without_metadata_sets_neither_user_nor_prompt_cache_key():
+    openai_request, _ = LiteLLMAnthropicMessagesAdapter().translate_anthropic_to_openai(
+        anthropic_message_request={
+            "model": "openai/gpt-5.6-luna",
+            "max_tokens": 100,
+            "messages": [{"role": "user", "content": "hi"}],
+        },
+        custom_llm_provider="openai",
+    )
+    assert "user" not in openai_request
+    assert "prompt_cache_key" not in openai_request
+
+
 def test_translate_openai_content_to_anthropic_empty_function_arguments():
     """Test that empty function arguments are handled safely and don't cause JSON parsing errors."""
 
diff --git a/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_handler_prompt_cache_key.py b/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_handler_prompt_cache_key.py
new file mode 100644
index 00000000000..ad6fc04217f
--- /dev/null
+++ b/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_handler_prompt_cache_key.py
@@ -0,0 +1,64 @@
+import os
+import sys
+
+import pytest
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../../../../../..")))
+
+from litellm.llms.anthropic.experimental_pass_through.adapters.handler import (
+    LiteLLMMessagesToCompletionTransformationHandler,
+)
+
+MESSAGES = [{"role": "user", "content": "hello"}]
+
+
+def _prepare(model: str, extra_kwargs: dict[str, object], thinking: dict[str, object] | None = None):
+    completion_kwargs, _ = LiteLLMMessagesToCompletionTransformationHandler._prepare_completion_kwargs(
+        max_tokens=1024,
+        messages=MESSAGES,
+        model=model,
+        metadata={"user_id": "session-abc"},
+        thinking=thinking,
+        extra_kwargs=extra_kwargs,
+    )
+    return completion_kwargs
+
+
+def test_prepare_completion_kwargs_derives_prompt_cache_key_for_openai_provider():
+    completion_kwargs = _prepare("openai/gpt-5.6-luna", {"custom_llm_provider": "openai"})
+    assert completion_kwargs["user"] == "session-abc"
+    assert completion_kwargs["prompt_cache_key"] == "session-abc"
+
+
+def test_prepare_completion_kwargs_prefers_explicit_prompt_cache_key_over_derived():
+    completion_kwargs = _prepare(
+        "openai/gpt-5.6-luna",
+        {"custom_llm_provider": "openai", "prompt_cache_key": "explicit-key"},
+    )
+    assert completion_kwargs["user"] == "session-abc"
+    assert completion_kwargs["prompt_cache_key"] == "explicit-key"
+
+
+@pytest.mark.parametrize(
+    "model, extra_kwargs",
+    [
+        ("gemini/gemini-2.5-pro", {"custom_llm_provider": "gemini"}),
+        ("openai/gpt-5.6-luna", {}),
+    ],
+)
+def test_prepare_completion_kwargs_skips_prompt_cache_key_without_provider_support(
+    model: str, extra_kwargs: dict[str, object]
+):
+    completion_kwargs = _prepare(model, extra_kwargs)
+    assert completion_kwargs["user"] == "session-abc"
+    assert "prompt_cache_key" not in completion_kwargs
+
+
+def test_prepare_completion_kwargs_keeps_prompt_cache_key_through_responses_reroute():
+    completion_kwargs = _prepare(
+        "openai/gpt-5.6-luna",
+        {"custom_llm_provider": "openai"},
+        thinking={"type": "enabled", "budget_tokens": 1024},
+    )
+    assert completion_kwargs["model"] == "responses/openai/gpt-5.6-luna"
+    assert completion_kwargs["prompt_cache_key"] == "session-abc"
diff --git a/tests/test_litellm/llms/anthropic/experimental_pass_through/responses_adapters/test_responses_adapters_handler.py b/tests/test_litellm/llms/anthropic/experimental_pass_through/responses_adapters/test_responses_adapters_handler.py
new file mode 100644
index 00000000000..7ef3077f9d7
--- /dev/null
+++ b/tests/test_litellm/llms/anthropic/experimental_pass_through/responses_adapters/test_responses_adapters_handler.py
@@ -0,0 +1,45 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../../../../../..")))
+
+from litellm.llms.anthropic.experimental_pass_through.responses_adapters.handler import (
+    _build_responses_kwargs,
+)
+
+MESSAGES = [{"role": "user", "content": "hello"}]
+
+
+def test_build_responses_kwargs_derives_prompt_cache_key_from_user_id():
+    responses_kwargs = _build_responses_kwargs(
+        max_tokens=1024,
+        messages=MESSAGES,
+        model="openai/gpt-5.6-luna",
+        metadata={"user_id": "session-abc"},
+        extra_kwargs={"custom_llm_provider": "openai"},
+    )
+    assert responses_kwargs["user"] == "session-abc"
+    assert responses_kwargs["prompt_cache_key"] == "session-abc"
+
+
+def test_build_responses_kwargs_prefers_explicit_prompt_cache_key_over_derived():
+    responses_kwargs = _build_responses_kwargs(
+        max_tokens=1024,
+        messages=MESSAGES,
+        model="openai/gpt-5.6-luna",
+        metadata={"user_id": "session-abc"},
+        extra_kwargs={"custom_llm_provider": "openai", "prompt_cache_key": "explicit-key"},
+    )
+    assert responses_kwargs["user"] == "session-abc"
+    assert responses_kwargs["prompt_cache_key"] == "explicit-key"
+
+
+def test_build_responses_kwargs_without_metadata_sets_no_prompt_cache_key():
+    responses_kwargs = _build_responses_kwargs(
+        max_tokens=1024,
+        messages=MESSAGES,
+        model="openai/gpt-5.6-luna",
+        extra_kwargs={"custom_llm_provider": "openai"},
+    )
+    assert "user" not in responses_kwargs
+    assert "prompt_cache_key" not in responses_kwargs
diff --git a/tests/test_litellm/llms/anthropic/experimental_pass_through/responses_adapters/test_responses_adapters_transformation.py b/tests/test_litellm/llms/anthropic/experimental_pass_through/responses_adapters/test_responses_adapters_transformation.py
index 876213eda3f..297f2052b83 100644
--- a/tests/test_litellm/llms/anthropic/experimental_pass_through/responses_adapters/test_responses_adapters_transformation.py
+++ b/tests/test_litellm/llms/anthropic/experimental_pass_through/responses_adapters/test_responses_adapters_transformation.py
@@ -992,6 +992,29 @@ class TestTranslateRequestBroaderCoverage:
         kwargs = _ADAPTER.translate_request(req)
         assert len(kwargs["user"]) == 64
 
+    def test_metadata_user_id_mapped_to_prompt_cache_key(self):
+        req = _make_request(metadata={"user_id": "user-42"})
+        kwargs = _ADAPTER.translate_request(req)
+        assert kwargs["prompt_cache_key"] == "user-42"
+
+    def test_metadata_user_id_prompt_cache_key_truncated_to_first_64_chars(self):
+        long_id = "".join(str(i % 10) for i in range(100))
+        req = _make_request(metadata={"user_id": long_id})
+        kwargs = _ADAPTER.translate_request(req)
+        assert kwargs["prompt_cache_key"] == long_id[:64]
+        assert len(kwargs["prompt_cache_key"]) == 64
+
+    def test_metadata_empty_user_id_sets_no_prompt_cache_key(self):
+        req = _make_request(metadata={"user_id": ""})
+        kwargs = _ADAPTER.translate_request(req)
+        assert kwargs["user"] == ""
+        assert "prompt_cache_key" not in kwargs
+
+    def test_metadata_null_user_id_sets_no_prompt_cache_key(self):
+        req = _make_request(metadata={"user_id": None})
+        kwargs = _ADAPTER.translate_request(req)
+        assert "prompt_cache_key" not in kwargs
+
     def test_no_optional_fields_does_not_add_spurious_keys(self):
         req = _make_request()
         kwargs = _ADAPTER.translate_request(req)
@@ -1005,6 +1028,7 @@ class TestTranslateRequestBroaderCoverage:
             "text",
             "context_management",
             "user",
+            "prompt_cache_key",
         ):
             assert key not in kwargs, f"unexpected key: {key}"
 

From 2c691d3820e25fa66224b89bccfcaf8476416ae5 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 04:10:10 -0700
Subject: [PATCH 12/35] feat(proxy): native CLI login with OAuth authorization
 code + PKCE

The proxy's OAuth authorization server (dynamic registration, PKCE S256,
loopback redirects, single-use codes, refresh rotation) gains a proxy-API
audience: /authorize?resource=<proxy origin> renders a consent page with
team selection and /token mints the same per-user credential lite login
mints, so a native CLI can sign a user in through the system browser and
call /v1/* with user and team attribution. Adds GET /.well-known/litellm-cli-auth
as the versioned discovery contract for non-Python clients, POST /revoke
(RFC 7009) for logout, and lite login --pkce, lite logout, and
lite auth print-token on the CLI side. Proxy-API grants only ever redirect
to a loopback address and the server never picks a team on the user's behalf.

Fixes #37332
---
 litellm/litellm_core_utils/cli_token_utils.py |   3 +
 .../mcp_server/bridge_token_flow.py           |  11 +-
 .../mcp_server/discoverable_endpoints.py      |  53 +-
 .../mcp_server/gateway_dcr_flow.py            | 500 +++++++++++++---
 .../outbound_credentials/session_token.py     |  19 +-
 .../mcp_server/proxy_api_credentials.py       |  84 +++
 litellm/proxy/_lazy_features.py               |   2 +
 litellm/proxy/client/cli/commands/auth.py     |  91 ++-
 .../proxy/client/cli/commands/pkce_login.py   | 471 +++++++++++++++
 .../html_forms/native_client_consent.py       |  91 +++
 litellm/proxy/management_endpoints/ui_sso.py  |  22 +-
 .../test_cli_token_utils.py                   |  27 +
 .../test_session_token.py                     |  52 ++
 .../mcp_server/test_discoverable_endpoints.py | 229 +++++++
 .../mcp_server/test_gateway_dcr_flow.py       | 564 +++++++++++++++++-
 .../mcp_server/test_proxy_api_credentials.py  | 167 ++++++
 .../proxy/client/cli/test_auth_commands.py    | 323 +++++++++-
 .../proxy/client/cli/test_pkce_login.py       | 553 +++++++++++++++++
 .../html_forms/test_native_client_consent.py  |  70 +++
 .../proxy/management_endpoints/test_ui_sso.py |  20 +-
 20 files changed, 3209 insertions(+), 143 deletions(-)
 create mode 100644 litellm/proxy/_experimental/mcp_server/proxy_api_credentials.py
 create mode 100644 litellm/proxy/client/cli/commands/pkce_login.py
 create mode 100644 litellm/proxy/common_utils/html_forms/native_client_consent.py
 create mode 100644 tests/test_litellm/proxy/_experimental/mcp_server/test_proxy_api_credentials.py
 create mode 100644 tests/test_litellm/proxy/client/cli/test_pkce_login.py
 create mode 100644 tests/test_litellm/proxy/common_utils/html_forms/test_native_client_consent.py

diff --git a/litellm/litellm_core_utils/cli_token_utils.py b/litellm/litellm_core_utils/cli_token_utils.py
index a44ce431f4e..0043bc31204 100644
--- a/litellm/litellm_core_utils/cli_token_utils.py
+++ b/litellm/litellm_core_utils/cli_token_utils.py
@@ -79,6 +79,9 @@ def is_cli_token_fresh(token_data: Mapping[str, object], buffer_hours: float = 0
     `LITELLM_CLI_JWT_EXPIRATION_HOURS`."""
     from litellm.constants import CLI_JWT_EXPIRATION_HOURS
 
+    expires_at: Final = token_data.get("expires_at")
+    if isinstance(expires_at, (int, float)):
+        return time.time() < expires_at - buffer_hours * 3600
     timestamp: Final = token_data.get("timestamp")
     if not isinstance(timestamp, (int, float)):
         return False
diff --git a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
index 1d8d545023d..b8c25236b0d 100644
--- a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
+++ b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
@@ -15,6 +15,7 @@ from litellm.proxy._experimental.mcp_server.oauth_utils import TOKEN_NO_CACHE_HE
 from litellm.types.mcp_server.mcp_server_manager import MCPServer
 
 if TYPE_CHECKING:
+    from litellm.models.user import LiteLLM_UserTable
     from litellm.proxy._experimental.mcp_server.discoverable_endpoints import _BridgeAuthorizationCode
     from litellm.proxy._experimental.mcp_server.outbound_credentials.envelope import (
         EnvelopeIdentity,
@@ -181,7 +182,13 @@ async def _reload_active_key_by_hash(key_hash: str) -> "_ResolvedKey | _KeyResol
 
 
 async def _reload_active_user_by_id(user_id: str) -> "_KeyResolutionFailure | None":
-    """Re-validate a live litellm user by id, returning ``None`` when the user is active or a precise
+    """``None`` when the user is live, else the precise failure ``load_active_user_by_id`` found."""
+    loaded: Final = await load_active_user_by_id(user_id)
+    return loaded if isinstance(loaded, str) else None
+
+
+async def load_active_user_by_id(user_id: str) -> "LiteLLM_UserTable | _KeyResolutionFailure":
+    """Load a live litellm user by id, returning the record when the user is active or a precise
     failure otherwise. The interactive DCR client authenticates via SSO, so its refresh envelope seals a
     user subject; renewing it must re-check the user is still live (present and not SCIM-deactivated) so a
     deactivated user cannot keep refreshing, mirroring how admission re-validates the same user subject on
@@ -226,7 +233,7 @@ async def _reload_active_user_by_id(user_id: str) -> "_KeyResolutionFailure | No
         return "no_active_key"
     if isinstance(user_object.metadata, dict) and user_object.metadata.get("scim_active") is False:
         return "no_active_key"
-    return None
+    return user_object
 
 
 async def _key_owner_scim_deactivated(key: "UserAPIKeyAuth") -> bool:
diff --git a/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py b/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
index 1ca4c657706..f9c5db76fa0 100644
--- a/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
+++ b/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
@@ -47,8 +47,12 @@ from litellm.proxy._experimental.mcp_server.gateway_dcr_flow import (
     aggregate_token,
     complete_connect_flow,
     is_gateway_dcr_client_id,
+    is_proxy_api_resource,
+    native_client_auth_contract,
+    native_client_authorize,
     register_aggregate_client,
     relative_request_url,
+    revoke_refresh_token,
 )
 from litellm.proxy._experimental.mcp_server.oauth_utils import (
     TOKEN_NO_CACHE_HEADERS,
@@ -58,6 +62,10 @@ from litellm.proxy._experimental.mcp_server.oauth_utils import (
     validate_trusted_redirect_uri,
     well_known_root_suffix,
 )
+from litellm.proxy._experimental.mcp_server.proxy_api_credentials import (
+    lookup_consent_teams,
+    mint_proxy_credential,
+)
 from litellm.proxy.auth.ip_address_utils import IPAddressUtils
 from litellm.proxy.common_utils.encrypt_decrypt_utils import (
     decrypt_value_helper,
@@ -1663,6 +1671,18 @@ async def authorize(
     )
 
     if mcp_server_name is None and client_id and is_gateway_dcr_client_id(client_id):
+        if is_proxy_api_resource(request, resource):
+            return await native_client_authorize(
+                request=request,
+                client_id=client_id,
+                redirect_uri=redirect_uri,
+                state=state,
+                code_challenge=code_challenge,
+                code_challenge_method=code_challenge_method,
+                response_type=response_type,
+                session_user_id=_session_cookie_user_id(request),
+                lookup_consent_teams=lookup_consent_teams,
+            )
         return aggregate_authorize(
             request=request,
             client_id=client_id,
@@ -1764,6 +1784,7 @@ async def token_endpoint(
             reload_user=_reload_active_user_by_id,
             cache=user_api_key_cache,
             resource=resource,
+            mint_proxy_credential=mint_proxy_credential,
         )
 
     lookup_name: Final = mcp_server_name or client_id
@@ -1793,12 +1814,19 @@ async def token_endpoint(
 
 
 @router.post("/authorize/complete")
-async def authorize_complete(request: Request, flow: str = Form(...), delivery: str | None = Form(None)):
+async def authorize_complete(
+    request: Request,
+    flow: str = Form(...),
+    delivery: str | None = Form(None),
+    team_id: str | None = Form(None),
+    decision: str | None = Form(None),
+) -> Response:
     """Finish an aggregate connect flow: mint the gateway authorization code for the
     signed-in user and hand it back to the DCR client, by 303 redirect (default) or, for
     a loopback client on a different machine, as a copyable callback URL
     (``delivery=manual``). POST plus the per-flow HttpOnly cookie set at /authorize; an
-    anonymous or bad-flow request just 400s."""
+    anonymous or bad-flow request just 400s. The native-client consent page adds
+    ``decision`` (approve or deny) and the ``team_id`` the credential is attributed to."""
     from litellm.proxy.proxy_server import user_api_key_cache  # noqa: PLC0415  # circular import at module load
 
     return await complete_connect_flow(
@@ -1807,9 +1835,30 @@ async def authorize_complete(request: Request, flow: str = Form(...), delivery:
         session_user_id=_session_cookie_user_id(request),
         cache=user_api_key_cache,
         delivery=delivery,
+        team_id=team_id,
+        decision=decision,
     )
 
 
+@router.post("/revoke")
+async def revoke_endpoint(request: Request, token: str = Form(...), client_id: str = Form(...)) -> Response:
+    """RFC 7009 revocation for the gateway's refresh tokens (``lite logout``). Always 200
+    for a known client, whatever the token's state; access tokens expire on their own."""
+    from litellm.proxy.proxy_server import (  # noqa: PLC0415  # circular import at module load
+        master_key,
+        user_api_key_cache,
+    )
+
+    return await revoke_refresh_token(token=token, client_id=client_id, master_key=master_key, cache=user_api_key_cache)
+
+
+@router.get("/.well-known/litellm-cli-auth")
+async def native_client_auth_discovery(request: Request) -> JSONResponse:
+    """The versioned contract a native client (``lite login --pkce``, or a CLI in any other
+    language) reads to sign a user in through the browser and obtain a proxy credential."""
+    return JSONResponse(native_client_auth_contract(request), headers=TOKEN_NO_CACHE_HEADERS)
+
+
 # Per RFC 6749 §4.1.2.1, an IdP that rejects an OAuth authorization request
 # redirects back to the configured redirect URI with ``error`` /
 # ``error_description`` / ``error_uri`` query params and no ``code``. The MCP
diff --git a/litellm/proxy/_experimental/mcp_server/gateway_dcr_flow.py b/litellm/proxy/_experimental/mcp_server/gateway_dcr_flow.py
index 85885fc75f5..53db6fbf9d1 100644
--- a/litellm/proxy/_experimental/mcp_server/gateway_dcr_flow.py
+++ b/litellm/proxy/_experimental/mcp_server/gateway_dcr_flow.py
@@ -42,15 +42,16 @@ import hmac
 import html
 import secrets
 from base64 import urlsafe_b64encode
-from collections.abc import Awaitable, Callable, Mapping
+from collections.abc import Awaitable, Callable, Iterable, Mapping
 from datetime import datetime, timezone
-from typing import Final, Literal, TypeVar
+from types import MappingProxyType
+from typing import Final, Literal, Protocol, TypeVar
 from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
 
 from fastapi import HTTPException, Request
 from fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse, Response
 from pydantic import BaseModel, ConfigDict, Field, ValidationError
-from typing_extensions import assert_never
+from typing_extensions import ReadOnly, TypedDict, assert_never
 
 from litellm._logging import verbose_logger
 from litellm.caching.caching import DualCache
@@ -70,6 +71,7 @@ from litellm.proxy._experimental.mcp_server.outbound_credentials.session_credent
 from litellm.proxy._experimental.mcp_server.outbound_credentials.session_token import (
     SESSION_REFRESH_TTL_SECONDS,
     MintedSessionToken,
+    SessionAudience,
     SessionKeys,
     SessionPrincipal,
     mint_session_refresh_token,
@@ -79,6 +81,9 @@ from litellm.proxy.common_utils.encrypt_decrypt_utils import (
     decrypt_value_helper,
     encrypt_value_helper,
 )
+from litellm.proxy.common_utils.html_forms.native_client_consent import (
+    render_native_client_consent_page,
+)
 from litellm.types.mcp_server.mcp_server_manager import MCPServer
 
 GATEWAY_DCR_CLIENT_ID_PREFIX: Final = "llm_dcrc_"
@@ -144,6 +149,46 @@ ReloadUser = Callable[[str], Awaitable[ReloadUserFailure | None]]
 ``None`` means the user is active; ``unavailable`` is a retryable DB outage; anything
 else fails the grant closed."""
 
+PROXY_API_AUDIENCE: Final[SessionAudience] = "proxy_api"
+"""The audience a native client (``lite login --pkce``, a Go CLI) asks for by sending the
+proxy base URL itself as the RFC 8707 ``resource``: the grant then mints the proxy-API CLI
+credential that LLM routes accept, instead of the MCP-only session pair."""
+
+ProxyCredentialMintFailure = Literal[ReloadUserFailure, "not_a_member"]
+
+
+class MintedProxyCredential(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    key: str = Field(min_length=1)
+    expires_in: int = Field(gt=0)
+    user_id: str = Field(min_length=1)
+    team_id: str | None = None
+
+
+class MintProxyCredential(Protocol):
+    """Injected proxy-API credential minter ``(user_id, team_id)``: reloads the user live,
+    checks team membership, and mints the same credential ``lite login`` mints."""
+
+    def __call__(
+        self, user_id: str, team_id: str | None, /
+    ) -> Awaitable[MintedProxyCredential | ProxyCredentialMintFailure]: ...
+
+
+class ConsentTeam(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    team_id: str = Field(min_length=1)
+    team_alias: str | None = None
+
+
+class LookupConsentTeams(Protocol):
+    """Injected lookup of the teams a signed-in user may bind a proxy-API credential to."""
+
+    def __call__(self, user_id: str, /) -> Awaitable[tuple[ConsentTeam, ...] | ReloadUserFailure]: ...
+
+
+async def _refuse_proxy_credential(user_id: str, team_id: str | None) -> ProxyCredentialMintFailure:
+    return "unresolvable"
+
 
 class GatewayDcrClient(BaseModel):
     """The registration record sealed into a gateway DCR ``client_id``.
@@ -173,6 +218,7 @@ class _ConnectFlow(BaseModel):
     jti: str = Field(min_length=1)
     exp: int
     resource_server_id: str | None = None
+    audience: SessionAudience | None = None
 
 
 class _GatewayAuthCode(BaseModel):
@@ -190,6 +236,8 @@ class _GatewayAuthCode(BaseModel):
     iat: int
     exp: int
     resource_server_id: str | None = None
+    audience: SessionAudience | None = None
+    team_id: str | None = None
 
 
 def is_gateway_dcr_client_id(client_id: str | None) -> bool:
@@ -318,9 +366,9 @@ def _cookie_path_and_secure(request: Request) -> tuple[str, bool]:
     return parsed.path or "/", parsed.scheme == "https"
 
 
-def _append_query_params(url: str, params: dict[str, str]) -> str:
+def _append_query_params(url: str, params: Iterable[tuple[str, str]]) -> str:
     parsed: Final = urlparse(url)
-    query: Final = parse_qsl(parsed.query, keep_blank_values=True) + list(params.items())
+    query: Final = (*parse_qsl(parsed.query, keep_blank_values=True), *params)
     return urlunparse(parsed._replace(query=urlencode(query)))
 
 
@@ -392,6 +440,155 @@ def aggregate_authorize(
     section 4.1.2.1 an unvalidated redirect URI must not receive an error redirect, and
     once the client is at fault there is no trusted place to send the browser.
     """
+    rejected: Final = _rejected_authorize_request(
+        client_id, redirect_uri, state, code_challenge, code_challenge_method, response_type
+    )
+    if rejected is not None:
+        return rejected
+    base_url: Final = get_request_base_url(request)
+    if session_user_id is None:
+        return _login_redirect(base_url, request)
+    scoped_server: Final = resolve_scoped_resource_server(request, resource)
+    handle: Final = secrets.token_urlsafe(24)
+    flow: Final = _new_connect_flow(
+        session_user_id=session_user_id,
+        client_id=client_id,
+        redirect_uri=redirect_uri,
+        state=state,
+        code_challenge=code_challenge or "",
+        resource_server_id=scoped_server.server_id if scoped_server is not None else None,
+        audience=None,
+    )
+    connect_url: Final = _append_query_params(
+        f"{base_url}/ui/connect",
+        (("connect_flow", handle), ("connect_client", _origin_only(redirect_uri))),
+    )
+    response: Final = RedirectResponse(connect_url, status_code=303)
+    _set_flow_cookie(response, request, handle, flow)
+    return response
+
+
+async def native_client_authorize(
+    request: Request,
+    client_id: str,
+    redirect_uri: str,
+    state: str,
+    code_challenge: str | None,
+    code_challenge_method: str | None,
+    response_type: str | None,
+    session_user_id: str | None,
+    lookup_consent_teams: LookupConsentTeams,
+) -> Response:
+    """The authorize verb for a native client that named the proxy API itself as its
+    RFC 8707 ``resource``: the same client, redirect, PKCE, and sign-in checks as the
+    aggregate verb plus a loopback-only redirect (the credential this grant mints is the
+    user's personal proxy key, which belongs on their own machine and never behind a hosted
+    callback), then the consent page rendered right here (no connect-page interlude, since
+    there is no per-server vaulting to do) with the flow sealed into the per-flow cookie
+    and its handle carried only in the form, never in a URL."""
+    rejected: Final = _rejected_authorize_request(
+        client_id, redirect_uri, state, code_challenge, code_challenge_method, response_type
+    )
+    if rejected is not None:
+        return rejected
+    if not is_loopback_redirect_host(urlparse(redirect_uri)):
+        return _oauth_error(400, "invalid_request", "a proxy-API grant may only redirect to a loopback address")
+    base_url: Final = get_request_base_url(request)
+    if session_user_id is None:
+        return _login_redirect(base_url, request)
+    teams: Final = await lookup_consent_teams(session_user_id)
+    if not isinstance(teams, tuple):
+        return _consent_lookup_failure_response(teams)
+    handle: Final = secrets.token_urlsafe(24)
+    flow: Final = _new_connect_flow(
+        session_user_id=session_user_id,
+        client_id=client_id,
+        redirect_uri=redirect_uri,
+        state=state,
+        code_challenge=code_challenge or "",
+        resource_server_id=None,
+        audience=PROXY_API_AUDIENCE,
+    )
+    page: Final = render_native_client_consent_page(
+        client_origin=_origin_only(redirect_uri),
+        user_id=session_user_id,
+        teams=tuple((team.team_id, team.team_alias or team.team_id) for team in teams),
+        flow_handle=handle,
+        complete_url=f"{base_url}/authorize/complete",
+    )
+    response: Final = HTMLResponse(page, headers=_CONSENT_PAGE_HEADERS)
+    _set_flow_cookie(response, request, handle, flow)
+    return response
+
+
+_CONSENT_PAGE_HEADERS: Final = MappingProxyType(
+    {
+        **TOKEN_NO_CACHE_HEADERS,
+        "X-Frame-Options": "DENY",
+        "Content-Security-Policy": "frame-ancestors 'none'",
+    }
+)
+
+NATIVE_CLIENT_AUTH_CONTRACT_VERSION: Final = 1
+"""The version a native client checks before trusting the rest of the discovery document.
+Bump it only when an existing field changes meaning or goes away; adding fields is free."""
+
+
+class NativeClientAuthContract(TypedDict):
+    contract_version: ReadOnly[int]
+    issuer: ReadOnly[str]
+    authorization_endpoint: ReadOnly[str]
+    token_endpoint: ReadOnly[str]
+    registration_endpoint: ReadOnly[str]
+    revocation_endpoint: ReadOnly[str]
+    resource: ReadOnly[str]
+    response_types_supported: ReadOnly[tuple[str, ...]]
+    grant_types_supported: ReadOnly[tuple[str, ...]]
+    code_challenge_methods_supported: ReadOnly[tuple[str, ...]]
+    token_endpoint_auth_methods_supported: ReadOnly[tuple[str, ...]]
+    revocation_endpoint_auth_methods_supported: ReadOnly[tuple[str, ...]]
+
+
+def native_client_auth_contract(request: Request) -> NativeClientAuthContract:
+    """The versioned discovery document at ``/.well-known/litellm-cli-auth``: everything a
+    native client (in any language) needs to run the sign-in without reading LiteLLM
+    source. ``resource`` is the exact value to send as the RFC 8707 ``resource`` parameter
+    on authorize and token requests so the grant is issued for the proxy API."""
+    base_url: Final = get_request_base_url(request)
+    contract: Final[NativeClientAuthContract] = {
+        "contract_version": NATIVE_CLIENT_AUTH_CONTRACT_VERSION,
+        "issuer": base_url,
+        "authorization_endpoint": f"{base_url}/authorize",
+        "token_endpoint": f"{base_url}/token",
+        "registration_endpoint": f"{base_url}/register",
+        "revocation_endpoint": f"{base_url}/revoke",
+        "resource": base_url,
+        "response_types_supported": ("code",),
+        "grant_types_supported": ("authorization_code", "refresh_token"),
+        "code_challenge_methods_supported": ("S256",),
+        "token_endpoint_auth_methods_supported": ("none",),
+        "revocation_endpoint_auth_methods_supported": ("none",),
+    }
+    return contract
+
+
+def is_proxy_api_resource(request: Request, resource: str | None) -> bool:
+    """True when the RFC 8707 ``resource`` names the proxy itself (its base URL), which is
+    how a native client asks for the proxy-API audience rather than an MCP session."""
+    if resource is None:
+        return False
+    canonical: Final = canonical_resource_uri(resource)
+    return canonical is not None and canonical == canonicalize_url_identity(get_request_base_url(request))
+
+
+def _rejected_authorize_request(
+    client_id: str,
+    redirect_uri: str,
+    state: str,
+    code_challenge: str | None,
+    code_challenge_method: str | None,
+    response_type: str | None,
+) -> Response | None:
     client: Final = open_gateway_dcr_client(client_id)
     if client is None:
         return _oauth_error(400, "invalid_client", "unknown or malformed client_id")
@@ -407,14 +604,25 @@ def aggregate_authorize(
         )
     if len(state) > MAX_STATE_LENGTH:
         return _oauth_error(400, "invalid_request", f"state must be at most {MAX_STATE_LENGTH} characters")
-    base_url: Final = get_request_base_url(request)
-    if session_user_id is None:
-        login_url: Final = f"{base_url}/sso/key/generate?{urlencode({'return_to': relative_request_url(request)})}"
-        return RedirectResponse(login_url, status_code=303)
+    return None
+
+
+def _login_redirect(base_url: str, request: Request) -> Response:
+    return_to: Final = urlencode((("return_to", relative_request_url(request)),))
+    return RedirectResponse(f"{base_url}/sso/key/generate?{return_to}", status_code=303)
+
+
+def _new_connect_flow(
+    session_user_id: str,
+    client_id: str,
+    redirect_uri: str,
+    state: str,
+    code_challenge: str,
+    resource_server_id: str | None,
+    audience: SessionAudience | None,
+) -> _ConnectFlow:
     now: Final = datetime.now(timezone.utc)
-    scoped_server: Final = resolve_scoped_resource_server(request, resource)
-    handle: Final = secrets.token_urlsafe(24)
-    flow: Final = _ConnectFlow(
+    return _ConnectFlow(
         user_id=session_user_id,
         client_id=client_id,
         redirect_uri=redirect_uri,
@@ -422,13 +630,12 @@ def aggregate_authorize(
         code_challenge=code_challenge,
         jti=secrets.token_urlsafe(24),
         exp=int(now.timestamp()) + CONNECT_FLOW_TTL_SECONDS,
-        resource_server_id=scoped_server.server_id if scoped_server is not None else None,
+        resource_server_id=resource_server_id,
+        audience=audience,
     )
-    connect_url: Final = _append_query_params(
-        f"{base_url}/ui/connect",
-        {"connect_flow": handle, "connect_client": _origin_only(redirect_uri)},
-    )
-    response: Final = RedirectResponse(connect_url, status_code=303)
+
+
+def _set_flow_cookie(response: Response, request: Request, handle: str, flow: _ConnectFlow) -> None:
     path, secure = _cookie_path_and_secure(request)
     response.set_cookie(
         key=_flow_cookie_name(handle),
@@ -439,7 +646,18 @@ def aggregate_authorize(
         httponly=True,
         samesite="lax",
     )
-    return response
+
+
+def _consent_lookup_failure_response(failure: ReloadUserFailure) -> Response:
+    match failure:
+        case "unavailable":
+            return _oauth_error(503, "temporarily_unavailable", "the gateway database is unavailable; retry")
+        case "unresolvable":
+            return _oauth_error(500, "server_error", "the gateway is not configured to resolve users")
+        case "no_active_key":
+            return _oauth_error(403, "access_denied", "the signed-in user is not active")
+        case _:
+            assert_never(failure)
 
 
 def _origin_only(url: str) -> str:
@@ -455,6 +673,8 @@ async def complete_connect_flow(
     session_user_id: str | None,
     cache: DualCache,
     delivery: str | None = None,
+    team_id: str | None = None,
+    decision: str | None = None,
 ) -> Response:
     """The deliberate finish step of the connect flow: mint the gateway authorization
     code and send the browser back to the client.
@@ -479,9 +699,16 @@ async def complete_connect_flow(
     party. Unknown ``delivery`` values are rejected rather than defaulted: a client that
     asked for manual delivery and got a dead redirect instead would silently lose its
     code.
+
+    ``decision`` and ``team_id`` come from the native-client consent page. ``"deny"``
+    burns the flow and sends the client ``error=access_denied`` so it stops waiting;
+    ``team_id`` is sealed into the code only for proxy-API flows, where it picks which of
+    the user's teams the minted credential is attributed to.
     """
     if delivery not in (None, "redirect", "manual"):
         return _oauth_error(400, "invalid_request", "delivery must be 'redirect' or 'manual'")
+    if decision not in (None, "approve", "deny"):
+        return _oauth_error(400, "invalid_request", "decision must be 'approve' or 'deny'")
     sealed_flow: Final = request.cookies.get(_flow_cookie_name(flow_handle))
     if sealed_flow is None:
         return _oauth_error(400, "invalid_request", "unknown or expired connect flow")
@@ -499,6 +726,24 @@ async def complete_connect_flow(
         f"{_USED_FLOW_CACHE_PREFIX}{flow.jti}", CONNECT_FLOW_TTL_SECONDS + _CLAIM_TTL_BUFFER_SECONDS
     ):
         return _oauth_error(400, "invalid_request", "this connect flow was already completed; restart the connection")
+    response: Final = (
+        _denied_flow_response(flow) if decision == "deny" else _approved_flow_response(flow, delivery, team_id, now)
+    )
+    path, secure = _cookie_path_and_secure(request)
+    response.delete_cookie(key=_flow_cookie_name(flow_handle), path=path, secure=secure, httponly=True, samesite="lax")
+    return response
+
+
+def _state_param(flow: _ConnectFlow) -> tuple[tuple[str, str], ...]:
+    return (("state", flow.state),) if flow.state else ()
+
+
+def _denied_flow_response(flow: _ConnectFlow) -> Response:
+    params: Final = (("error", "access_denied"), *_state_param(flow))
+    return RedirectResponse(_append_query_params(flow.redirect_uri, params), status_code=303)
+
+
+def _approved_flow_response(flow: _ConnectFlow, delivery: str | None, team_id: str | None, now: datetime) -> Response:
     manual_delivery: Final = delivery == "manual" and is_loopback_redirect_host(urlparse(flow.redirect_uri))
     code_ttl: Final = MANUAL_DELIVERY_AUTH_CODE_TTL_SECONDS if manual_delivery else GATEWAY_AUTH_CODE_TTL_SECONDS
     code: Final = _seal(
@@ -512,16 +757,14 @@ async def complete_connect_flow(
             iat=int(now.timestamp()),
             exp=int(now.timestamp()) + code_ttl,
             resource_server_id=flow.resource_server_id,
+            audience=flow.audience,
+            team_id=(team_id or None) if flow.audience == PROXY_API_AUDIENCE else None,
         ),
     )
-    params: Final = {"code": code, **({"state": flow.state} if flow.state else {})}
-    callback_url: Final = _append_query_params(flow.redirect_uri, params)
-    response: Final[Response] = (
-        _manual_delivery_response(callback_url) if manual_delivery else RedirectResponse(callback_url, status_code=303)
-    )
-    path, secure = _cookie_path_and_secure(request)
-    response.delete_cookie(key=_flow_cookie_name(flow_handle), path=path, secure=secure, httponly=True, samesite="lax")
-    return response
+    callback_url: Final = _append_query_params(flow.redirect_uri, (("code", code), *_state_param(flow)))
+    if manual_delivery:
+        return _manual_delivery_response(callback_url)
+    return RedirectResponse(callback_url, status_code=303)
 
 
 def _manual_delivery_response(callback_url: str) -> Response:
@@ -630,6 +873,37 @@ def _session_token_pair(principal: SessionPrincipal, keys: SessionKeys, now: dat
     )
 
 
+class _ProxyCredentialTokenResponse(TypedDict):
+    access_token: ReadOnly[str]
+    token_type: ReadOnly[Literal["Bearer"]]
+    expires_in: ReadOnly[int]
+    refresh_token: ReadOnly[str]
+    user_id: ReadOnly[str]
+    team_id: ReadOnly[str | None]
+
+
+def _proxy_credential_response(
+    minted: MintedProxyCredential, principal: SessionPrincipal, keys: SessionKeys, now: datetime
+) -> Response:
+    """The proxy-API token response: the access token is the very credential ``lite
+    login`` stores (accepted on every proxy route with user and team attribution), and
+    the refresh token is a gateway-sealed rotating token bound to the team the credential
+    was minted for, so a renewal keeps the team the user consented to."""
+    bound_principal: Final = principal.model_copy(update=MappingProxyType({"team_id": minted.team_id}))
+    refresh: Final = mint_session_refresh_token(bound_principal, keys, now)
+    if not isinstance(refresh, MintedSessionToken):
+        return _oauth_error(500, "server_error", "failed to mint the session credential")
+    body: Final[_ProxyCredentialTokenResponse] = {
+        "access_token": minted.key,
+        "token_type": "Bearer",
+        "expires_in": minted.expires_in,
+        "refresh_token": refresh.token.get_secret_value(),
+        "user_id": minted.user_id,
+        "team_id": minted.team_id,
+    }
+    return JSONResponse(status_code=200, content=body, headers=TOKEN_NO_CACHE_HEADERS)
+
+
 def _reload_failure_response(failure: ReloadUserFailure) -> Response:
     """Map the live-user revalidation failure onto its OAuth error, exhaustively, so a new
     ``ReloadUserFailure`` member is a type error here rather than silently 400ing."""
@@ -644,6 +918,18 @@ def _reload_failure_response(failure: ReloadUserFailure) -> Response:
             assert_never(failure)
 
 
+def _mint_failure_response(failure: ProxyCredentialMintFailure) -> Response:
+    match failure:
+        case "not_a_member":
+            return _oauth_error(
+                400, "invalid_grant", "the user is no longer a member of the team this grant was issued for"
+            )
+        case "unavailable" | "unresolvable" | "no_active_key":
+            return _reload_failure_response(failure)
+        case _:
+            assert_never(failure)
+
+
 def _resource_conflicts_with_scope(
     request: Request, resource: str | None, sealed_resource_server_id: str | None
 ) -> bool:
@@ -670,15 +956,26 @@ async def aggregate_token(
     reload_user: ReloadUser,
     cache: DualCache,
     resource: str | None = None,
+    mint_proxy_credential: MintProxyCredential = _refuse_proxy_credential,
 ) -> Response:
     """The aggregate token verb: authorization_code and refresh_token grants for the
-    identity-only session pair. Every path re-validates the litellm user live before
-    minting, so a deactivated user cannot obtain or renew a session."""
+    identity-only session pair, or for the proxy-API credential when the grant was issued
+    with that audience. Every path re-validates the litellm user live before minting, so a
+    deactivated user cannot obtain or renew a session."""
     if master_key is None:
         verbose_logger.error("mcp_gateway_dcr token grant rejected: no master_key configured")
         return _oauth_error(500, "server_error", "the gateway has no master key configured")
     keys: Final = session_keys_from_master_key(master_key)
     now: Final = datetime.now(timezone.utc)
+    issue: Final = _GrantIssuer(
+        request=request,
+        resource=resource,
+        keys=keys,
+        now=now,
+        reload_user=reload_user,
+        mint_proxy_credential=mint_proxy_credential,
+        guard=_SingleUseGuard(cache),
+    )
     if grant_type == "authorization_code":
         return await _authorization_code_grant(
             request=request,
@@ -687,10 +984,8 @@ async def aggregate_token(
             client_id=client_id,
             code_verifier=code_verifier,
             resource=resource,
-            keys=keys,
             now=now,
-            reload_user=reload_user,
-            guard=_SingleUseGuard(cache),
+            issue=issue,
         )
     if grant_type == "refresh_token":
         return await _refresh_token_grant(
@@ -700,12 +995,71 @@ async def aggregate_token(
             resource=resource,
             keys=keys,
             now=now,
-            reload_user=reload_user,
-            guard=_SingleUseGuard(cache),
+            issue=issue,
         )
     return _oauth_error(400, "unsupported_grant_type", "grant_type must be authorization_code or refresh_token")
 
 
+class _GrantIssuer:
+    """The tail every grant shares once its own proof (code + PKCE, or a refresh token)
+    has checked out: revalidate the user live, claim the single-use marker, mint. The
+    claim comes AFTER revalidation and minting so a transient DB 503 never burns a
+    still-valid code or refresh token, and fails closed when it cannot be recorded."""
+
+    def __init__(
+        self,
+        request: Request,
+        resource: str | None,
+        keys: SessionKeys,
+        now: datetime,
+        reload_user: ReloadUser,
+        mint_proxy_credential: MintProxyCredential,
+        guard: _SingleUseGuard,
+    ) -> None:
+        self._request: Final = request
+        self._resource: Final = resource
+        self._keys: Final = keys
+        self._now: Final = now
+        self._reload_user: Final = reload_user
+        self._mint_proxy_credential: Final = mint_proxy_credential
+        self._guard: Final = guard
+
+    async def __call__(
+        self, principal: SessionPrincipal, claim_key: str, claim_ttl_seconds: int, replayed: str
+    ) -> Response:
+        match principal.audience:
+            case None:
+                return await self._issue_session_pair(principal, claim_key, claim_ttl_seconds, replayed)
+            case "proxy_api":
+                return await self._issue_proxy_credential(principal, claim_key, claim_ttl_seconds, replayed)
+            case _:
+                assert_never(principal.audience)
+
+    async def _issue_session_pair(
+        self, principal: SessionPrincipal, claim_key: str, claim_ttl_seconds: int, replayed: str
+    ) -> Response:
+        failure: Final = await self._reload_user(principal.user_id)
+        if failure is not None:
+            return _reload_failure_response(failure)
+        if not await self._guard.claim(claim_key, claim_ttl_seconds):
+            return _oauth_error(400, "invalid_grant", replayed)
+        return _session_token_pair(principal, self._keys, self._now)
+
+    async def _issue_proxy_credential(
+        self, principal: SessionPrincipal, claim_key: str, claim_ttl_seconds: int, replayed: str
+    ) -> Response:
+        if self._resource is not None and not is_proxy_api_resource(self._request, self._resource):
+            return _oauth_error(
+                400, "invalid_target", "resource does not match the proxy API this grant was issued for"
+            )
+        minted: Final = await self._mint_proxy_credential(principal.user_id, principal.team_id)
+        if not isinstance(minted, MintedProxyCredential):
+            return _mint_failure_response(minted)
+        if not await self._guard.claim(claim_key, claim_ttl_seconds):
+            return _oauth_error(400, "invalid_grant", replayed)
+        return _proxy_credential_response(minted, principal, self._keys, self._now)
+
+
 async def _authorization_code_grant(
     request: Request,
     code: str | None,
@@ -713,10 +1067,8 @@ async def _authorization_code_grant(
     client_id: str,
     code_verifier: str | None,
     resource: str | None,
-    keys: SessionKeys,
     now: datetime,
-    reload_user: ReloadUser,
-    guard: _SingleUseGuard,
+    issue: _GrantIssuer,
 ) -> Response:
     if not code or not redirect_uri or not code_verifier:
         return _oauth_error(400, "invalid_request", "code, redirect_uri, and code_verifier are required")
@@ -733,23 +1085,19 @@ async def _authorization_code_grant(
         return _oauth_error(400, "invalid_target", "resource does not match the scope this code was issued for")
     if not _pkce_verifier_matches(code_verifier, parsed.code_challenge):
         return _oauth_error(400, "invalid_grant", "PKCE verification failed")
-    # Revalidate the user BEFORE claiming the code, so a transient DB outage (a retryable
-    # 503) does not consume a still-valid code and force the client to restart sign-in.
-    failure: Final = await reload_user(parsed.user_id)
-    if failure is not None:
-        return _reload_failure_response(failure)
-    # Atomic single-use claim is the gate: on a concurrent double-redeem exactly one caller
-    # wins, and a claim that cannot be recorded fails closed. The marker's TTL derives from
-    # the code's own remaining lifetime so it outlives whichever lifetime the code was minted with.
-    if not await guard.claim(
-        f"{_USED_CODE_CACHE_PREFIX}{parsed.jti}",
-        parsed.exp - int(now.timestamp()) + _CLAIM_TTL_BUFFER_SECONDS,
-    ):
-        return _oauth_error(400, "invalid_grant", "the authorization code was already used")
-    return _session_token_pair(
-        SessionPrincipal(user_id=parsed.user_id, client_id=client_id, resource_server_id=parsed.resource_server_id),
-        keys,
-        now,
+    # The marker's TTL derives from the code's own remaining lifetime so it outlives
+    # whichever lifetime the code was minted with.
+    return await issue(
+        SessionPrincipal(
+            user_id=parsed.user_id,
+            client_id=client_id,
+            resource_server_id=parsed.resource_server_id,
+            audience=parsed.audience,
+            team_id=parsed.team_id,
+        ),
+        claim_key=f"{_USED_CODE_CACHE_PREFIX}{parsed.jti}",
+        claim_ttl_seconds=parsed.exp - int(now.timestamp()) + _CLAIM_TTL_BUFFER_SECONDS,
+        replayed="the authorization code was already used",
     )
 
 
@@ -760,8 +1108,7 @@ async def _refresh_token_grant(
     resource: str | None,
     keys: SessionKeys,
     now: datetime,
-    reload_user: ReloadUser,
-    guard: _SingleUseGuard,
+    issue: _GrantIssuer,
 ) -> Response:
     if not refresh_token:
         return _oauth_error(400, "invalid_request", "refresh_token is required")
@@ -770,16 +1117,33 @@ async def _refresh_token_grant(
         return _oauth_error(400, "invalid_grant", "the refresh token is invalid for this client")
     if _resource_conflicts_with_scope(request, resource, opened.principal.resource_server_id):
         return _oauth_error(400, "invalid_target", "resource does not match the scope this token was issued for")
-    failure: Final = await reload_user(opened.principal.user_id)
-    if failure is not None:
-        return _reload_failure_response(failure)
     # Refresh-token rotation (OAuth 2.0 Security BCP section 4.13): the presented refresh token is
-    # single-use. Claim its jti before issuing the replacement pair, so a captured or replayed
-    # refresh token cannot mint a second pair after the legitimate holder rotated. Claimed AFTER
-    # user revalidation so a transient DB 503 does not burn a still-valid token; a claim that
-    # cannot be recorded fails closed, exactly like the authorization-code path.
-    if not await guard.claim(
-        f"{_USED_REFRESH_CACHE_PREFIX}{opened.jti}", SESSION_REFRESH_TTL_SECONDS + _CLAIM_TTL_BUFFER_SECONDS
-    ):
-        return _oauth_error(400, "invalid_grant", "the refresh token was already used")
-    return _session_token_pair(opened.principal, keys, now)
+    # single-use, so a captured or replayed refresh token cannot mint a second pair after the
+    # legitimate holder rotated.
+    return await issue(
+        opened.principal,
+        claim_key=f"{_USED_REFRESH_CACHE_PREFIX}{opened.jti}",
+        claim_ttl_seconds=SESSION_REFRESH_TTL_SECONDS + _CLAIM_TTL_BUFFER_SECONDS,
+        replayed="the refresh token was already used",
+    )
+
+
+async def revoke_refresh_token(token: str, client_id: str, master_key: str | None, cache: DualCache) -> Response:
+    """RFC 7009 revocation for the gateway's refresh tokens: burn the presented token's
+    ``jti`` so neither the holder nor a thief can rotate it again. Access tokens are
+    stateless and expire on their own (the proxy-API credential within
+    ``CLI_JWT_EXPIRATION_HOURS``), so per RFC 7009 section 2.2 an unrecognized or already
+    dead token still answers 200; only an unknown client is refused."""
+    if not is_gateway_dcr_client_id(client_id) or open_gateway_dcr_client(client_id) is None:
+        return _oauth_error(401, "invalid_client", "unknown or malformed client_id")
+    if master_key is None:
+        verbose_logger.error("mcp_gateway_dcr revoke rejected: no master_key configured")
+        return _oauth_error(500, "server_error", "the gateway has no master key configured")
+    keys: Final = session_keys_from_master_key(master_key)
+    now: Final = datetime.now(timezone.utc)
+    opened: Final = open_session_refresh_bearer(token, keys, now, expected_client_id=client_id)
+    if isinstance(opened, SessionRefreshOpened):
+        _ = await _SingleUseGuard(cache).claim(
+            f"{_USED_REFRESH_CACHE_PREFIX}{opened.jti}", SESSION_REFRESH_TTL_SECONDS + _CLAIM_TTL_BUFFER_SECONDS
+        )
+    return Response(content="{}", media_type="application/json", headers=TOKEN_NO_CACHE_HEADERS)
diff --git a/litellm/proxy/_experimental/mcp_server/outbound_credentials/session_token.py b/litellm/proxy/_experimental/mcp_server/outbound_credentials/session_token.py
index 15f5f82c4b6..d6b0a462062 100644
--- a/litellm/proxy/_experimental/mcp_server/outbound_credentials/session_token.py
+++ b/litellm/proxy/_experimental/mcp_server/outbound_credentials/session_token.py
@@ -76,6 +76,13 @@ SessionTokenKind = Literal["session", "session_refresh"]
 on open, so a signature-valid token of one kind cannot be replayed as the other even if its
 wire prefix is swapped (the prefix is not part of the signed payload; this claim is)."""
 
+SessionAudience = Literal["proxy_api"]
+"""The non-MCP audience a session REFRESH token can be minted for. ``None`` (the default and
+the only value ever on an MCP wire) means the aggregate MCP gateway; ``"proxy_api"`` means the
+refresh grant re-mints the proxy-API CLI credential instead of an MCP session pair. The audience
+is read only from the signed claims, never from the request, so a token of one audience can
+never be redeemed as the other."""
+
 
 class SessionPrincipal(BaseModel):
     """The litellm user a session token identifies and the DCR client it was issued to.
@@ -97,6 +104,8 @@ class SessionPrincipal(BaseModel):
     user_id: str = Field(min_length=1)
     client_id: str = Field(min_length=1)
     resource_server_id: str | None = None
+    audience: SessionAudience | None = None
+    team_id: str | None = None
 
 
 class SessionKeys(BaseModel):
@@ -194,6 +203,8 @@ class _SessionClaims(BaseModel):
     user_id: str = Field(min_length=1)
     client_id: str = Field(min_length=1)
     resource_server_id: str | None = None
+    audience: SessionAudience | None = None
+    team_id: str | None = None
 
 
 def is_session_token(candidate: str) -> bool:
@@ -295,6 +306,8 @@ def _mint(
         user_id=principal.user_id,
         client_id=principal.client_id,
         resource_server_id=principal.resource_server_id,
+        audience=principal.audience,
+        team_id=principal.team_id,
     )
     token: Final = prefix + jwt.encode(
         claims.model_dump(exclude_none=True), keys.signing_key.get_secret_value(), algorithm=_SESSION_JWT_ALGORITHM
@@ -333,7 +346,11 @@ def _open(
         return SessionExpired()
     return OpenedSessionToken(
         principal=SessionPrincipal(
-            user_id=claims.user_id, client_id=claims.client_id, resource_server_id=claims.resource_server_id
+            user_id=claims.user_id,
+            client_id=claims.client_id,
+            resource_server_id=claims.resource_server_id,
+            audience=claims.audience,
+            team_id=claims.team_id,
         ),
         jti=claims.jti,
     )
diff --git a/litellm/proxy/_experimental/mcp_server/proxy_api_credentials.py b/litellm/proxy/_experimental/mcp_server/proxy_api_credentials.py
new file mode 100644
index 00000000000..a24afc529bd
--- /dev/null
+++ b/litellm/proxy/_experimental/mcp_server/proxy_api_credentials.py
@@ -0,0 +1,84 @@
+"""The proxy-API side of the native-client sign-in: turning a consented OAuth grant into
+the same per-user credential ``lite login`` stores, so the bearer a CLI obtains through
+the browser flow is accepted on every proxy route with user and team attribution."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Final
+
+from litellm.constants import CLI_JWT_EXPIRATION_HOURS
+from litellm.proxy._experimental.mcp_server.bridge_token_flow import load_active_user_by_id
+from litellm.proxy._experimental.mcp_server.gateway_dcr_flow import (
+    ConsentTeam,
+    MintedProxyCredential,
+    ProxyCredentialMintFailure,
+    ReloadUserFailure,
+)
+from litellm.proxy._types import LiteLLM_UserTable
+from litellm.proxy.auth.auth_checks import ExperimentalUIJWTToken
+from litellm.proxy.management_endpoints.ui_sso import (
+    CliSsoTeamDetail,
+    fetch_cli_sso_team_details,
+    selected_cli_sso_team_detail,
+)
+
+
+async def lookup_consent_teams(user_id: str) -> tuple[ConsentTeam, ...] | ReloadUserFailure:
+    user: Final = await load_active_user_by_id(user_id)
+    if isinstance(user, str):
+        return user
+    details: Final = await _team_details(user.teams)
+    if details is None:
+        return "unavailable"
+    return tuple(
+        ConsentTeam(team_id=detail.team_id, team_alias=detail.team_alias)
+        for detail in details
+        if detail.team_id is not None
+    )
+
+
+async def mint_proxy_credential(
+    user_id: str, team_id: str | None
+) -> MintedProxyCredential | ProxyCredentialMintFailure:
+    """Mint the ``lite login`` credential for a consented grant. Membership is checked
+    live, so a team the user left between consent and redemption (or between refreshes)
+    refuses the grant instead of minting a credential attributed to a team they are no
+    longer on. The team is exactly the one the consent page sealed into the grant; nothing
+    is picked on the user's behalf here, so a refresh can never move the credential. The
+    user row handed to the minter carries no team list, exactly like ``lite login``'s, so
+    the minter's own first-team fallback stays inert."""
+    user: Final = await load_active_user_by_id(user_id)
+    if isinstance(user, str):
+        return user
+    if user.user_role is None:
+        return "no_active_key"
+    if team_id is not None and team_id not in user.teams:
+        return "not_a_member"
+    details: Final = await _team_details(user.teams) if team_id is not None else ()
+    if details is None:
+        return "unavailable"
+    selected: Final = selected_cli_sso_team_detail(details, team_id)
+    if selected is None:
+        return "not_a_member"
+    key: Final = ExperimentalUIJWTToken.get_cli_jwt_auth_token(
+        user_info=LiteLLM_UserTable(user_id=user.user_id, user_role=user.user_role, models=user.models),
+        team_id=team_id,
+        team_alias=selected.team_alias,
+        team_models=selected.team_models,
+        team_model_aliases=selected.team_model_aliases,
+    )
+    return MintedProxyCredential(
+        key=key,
+        expires_in=CLI_JWT_EXPIRATION_HOURS * 3600,
+        user_id=user.user_id,
+        team_id=team_id,
+    )
+
+
+async def _team_details(teams: Sequence[str]) -> tuple[CliSsoTeamDetail, ...] | None:
+    from litellm.proxy.proxy_server import prisma_client  # noqa: PLC0415  # rebound after startup, so read it per call
+
+    if prisma_client is None:
+        return None
+    return await fetch_cli_sso_team_details(prisma_client, teams)
diff --git a/litellm/proxy/_lazy_features.py b/litellm/proxy/_lazy_features.py
index 262d97e4579..fdd15a89aa5 100644
--- a/litellm/proxy/_lazy_features.py
+++ b/litellm/proxy/_lazy_features.py
@@ -155,10 +155,12 @@ LAZY_FEATURES: Final[tuple[LazyFeature, ...]] = (
             "/.well-known/oauth-",
             "/.well-known/openid-configuration",
             "/.well-known/jwks.json",
+            "/.well-known/litellm-cli-auth",
             "/authorize",
             "/token",
             "/callback",
             "/register",
+            "/revoke",
         ),
         # Catches the /{mcp_server_name}/authorize|token|register variants.
         path_suffixes=("/authorize", "/token", "/register"),
diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py
index 0a0bcf80ee5..aee715686b7 100644
--- a/litellm/proxy/client/cli/commands/auth.py
+++ b/litellm/proxy/client/cli/commands/auth.py
@@ -11,7 +11,7 @@ import click
 import requests
 from rich.console import Console
 from rich.table import Table
-from typing_extensions import NotRequired, TypedDict
+from typing_extensions import NotRequired, ReadOnly, TypedDict
 
 from litellm.constants import CLI_JWT_EXPIRATION_HOURS
 from litellm.litellm_core_utils.cli_token_utils import is_cli_token_fresh
@@ -22,6 +22,13 @@ from .claude_settings import (
     ClaudeSettingsError,
     write_claude_settings,
 )
+from .pkce_login import (
+    PkceFailure,
+    fresh_api_key,
+    pkce_token_record,
+    revoke_stored_credential,
+    run_pkce_login,
+)
 from .private_json import write_private_json
 
 
@@ -34,6 +41,13 @@ class CliTokenData(TypedDict):
     auth_header_name: str
     jwt_token: str
     timestamp: float
+    expires_at: ReadOnly[NotRequired[float]]
+    refresh_token: ReadOnly[NotRequired[str]]
+    client_id: ReadOnly[NotRequired[str]]
+    token_endpoint: ReadOnly[NotRequired[str]]
+    revocation_endpoint: ReadOnly[NotRequired[str]]
+    resource: ReadOnly[NotRequired[str]]
+    team_id: ReadOnly[NotRequired[str | None]]
 
 
 class CliTeam(TypedDict, total=False):
@@ -79,10 +93,7 @@ class CliAuthResult(TypedDict):
 # Token storage utilities
 def get_token_file_path() -> str:
     """Get the path to store the authentication token"""
-    home_dir: Final = Path.home()
-    config_dir: Final = home_dir / ".litellm"
-    config_dir.mkdir(exist_ok=True)
-    return str(config_dir / "token.json")
+    return str(Path.home() / ".litellm" / "token.json")
 
 
 def save_token(token_data: CliTokenData) -> None:
@@ -115,11 +126,15 @@ def get_stored_api_key(expected_base_url: str | None = None) -> str | None:
 
     If expected_base_url is provided, the key is only returned when it was
     originally issued for that URL. This prevents credential leakage when the
-    CLI is pointed at a different (possibly malicious) server.
+    CLI is pointed at a different (possibly malicious) server. A key obtained by
+    ``lite login --pkce`` is refreshed here once it nears expiry.
     """
-    from litellm.litellm_core_utils.cli_token_utils import get_litellm_gateway_api_key
-
-    return get_litellm_gateway_api_key(expected_base_url=expected_base_url)
+    token_data: Final = load_token()
+    if token_data is None:
+        return None
+    if expected_base_url is not None and token_data.get("base_url") != expected_base_url.rstrip("/"):
+        return None
+    return fresh_api_key(token_data, save_token, requests.Session(), reload=load_token)
 
 
 # Team selection utilities
@@ -645,6 +660,27 @@ def _configure_claude_code(base_url: str) -> None:
     click.echo("Your other Claude Code settings were left untouched. Restart Claude Code to pick this up.")
 
 
+def _finish_login(base_url: str, api_key: str, config_claude: bool) -> None:
+    from litellm.proxy.client.cli.interface import show_commands
+
+    click.echo("\nLogin successful!")
+    click.echo(f"JWT Token: {api_key[:20]}...")
+    click.echo("You can now use the CLI without specifying --api-key")
+    if config_claude:
+        _configure_claude_code(base_url)
+    click.echo("\n" + "=" * 60)
+    show_commands()
+
+
+def _pkce_login(base_url: str, config_claude: bool) -> None:
+    credential: Final = run_pkce_login(base_url, requests.Session(), echo=click.echo)
+    if isinstance(credential, PkceFailure):
+        click.echo(f"Authentication failed: {credential.reason}")
+        return
+    save_token(pkce_token_record(base_url, credential))
+    _finish_login(base_url, credential.access_token, config_claude)
+
+
 @click.command(name="login")
 @click.option(
     "--config-claude",
@@ -655,16 +691,28 @@ def _configure_claude_code(base_url: str) -> None:
         "Unrelated settings are preserved."
     ),
 )
+@click.option(
+    "--pkce",
+    is_flag=True,
+    default=False,
+    help=(
+        "Sign in with OAuth authorization code + PKCE through your system browser (loopback redirect), "
+        "with a refresh token that renews the key automatically. Requires a proxy that serves "
+        "/.well-known/litellm-cli-auth."
+    ),
+)
 @click.pass_context
-def login(ctx: click.Context, config_claude: bool):
+def login(ctx: click.Context, config_claude: bool, pkce: bool) -> None:
     """Login to LiteLLM proxy using SSO authentication"""
     from litellm.constants import LITELLM_CLI_SOURCE_IDENTIFIER
-    from litellm.proxy.client.cli.interface import show_commands
 
     ctx_obj: Final[CliContextObj] = ctx.obj
     base_url: Final = ctx_obj["base_url"]
 
     try:
+        if pkce:
+            _pkce_login(base_url, config_claude)
+            return
         cli_sso_flow: Final = _start_cli_sso_flow(base_url=base_url)
         key_id: Final = cli_sso_flow["login_id"]
         poll_secret: Final = cli_sso_flow["poll_secret"]
@@ -704,16 +752,7 @@ def login(ctx: click.Context, config_claude: bool):
                 }
             )
 
-            click.echo("\nLogin successful!")
-            click.echo(f"JWT Token: {api_key[:20]}...")
-            click.echo("You can now use the CLI without specifying --api-key")
-
-            if config_claude:
-                _configure_claude_code(base_url)
-
-            # Show available commands after successful login
-            click.echo("\n" + "=" * 60)
-            show_commands()
+            _finish_login(base_url, api_key, config_claude)
             return
         else:
             click.echo("Authentication timed out. Please try again.")
@@ -738,7 +777,11 @@ def login(ctx: click.Context, config_claude: bool):
 @click.command(name="logout")
 def logout():
     """Logout and clear stored authentication"""
+    token_data: Final = load_token()
+    revocation: Final = revoke_stored_credential(token_data, requests.Session()) if token_data is not None else None
     clear_token()
+    if revocation is not None:
+        click.echo(f"Could not revoke the refresh token on the proxy ({revocation.reason}); it expires on its own.")
     click.echo("Logged out successfully. Authentication token cleared.")
 
 
@@ -769,13 +812,13 @@ def print_token(ctx: click.Context):
             click.echo("Not authenticated for this server. Run 'lite login'.", err=True)
             sys.exit(1)
 
-    if not is_cli_token_fresh(token_data):
+    if not is_cli_token_fresh(token_data) and "refresh_token" not in token_data:
         click.echo("Token expired. Run 'lite login' again.", err=True)
         sys.exit(1)
 
-    api_key: Final = token_data.get("key")
+    api_key: Final = fresh_api_key(token_data, save_token, requests.Session(), reload=load_token)
     if not api_key:
-        click.echo("No token available. Run 'lite login'.", err=True)
+        click.echo("Token expired. Run 'lite login' again.", err=True)
         sys.exit(1)
 
     click.echo(api_key)
diff --git a/litellm/proxy/client/cli/commands/pkce_login.py b/litellm/proxy/client/cli/commands/pkce_login.py
new file mode 100644
index 00000000000..6d6646a886c
--- /dev/null
+++ b/litellm/proxy/client/cli/commands/pkce_login.py
@@ -0,0 +1,471 @@
+"""Browser sign-in for ``lite login --pkce``: OAuth 2.1 authorization code + PKCE S256
+against the proxy's own authorization server, as a public client on a loopback redirect.
+The proxy publishes everything this needs at ``/.well-known/litellm-cli-auth``, so a CLI
+in any other language can run the same steps from that document alone."""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+import socket
+import threading
+import time
+import webbrowser
+from base64 import urlsafe_b64encode
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Final, Literal, Protocol
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import requests
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, ValidationError
+from typing_extensions import ReadOnly, TypedDict
+
+if TYPE_CHECKING:
+    from .auth import CliTokenData
+
+CLI_AUTH_DISCOVERY_PATH: Final = "/.well-known/litellm-cli-auth"
+CALLBACK_PATH: Final = "/callback"
+LOGIN_TIMEOUT_SECONDS: Final = 300
+REFRESH_LEEWAY_SECONDS: Final = 60
+_HTTP_TIMEOUT_SECONDS: Final = 15
+_CLIENT_NAME: Final = "litellm-cli"
+
+
+class CliAuthContract(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    contract_version: Literal[1]
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+    registration_endpoint: str
+    revocation_endpoint: str
+    resource: str
+    code_challenge_methods_supported: tuple[str, ...]
+
+
+class _RegisteredClient(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    client_id: str = Field(min_length=1)
+
+
+class _TokenResponse(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    access_token: str = Field(min_length=1)
+    expires_in: int = Field(gt=0)
+    refresh_token: str = Field(min_length=1)
+    user_id: str | None = None
+    team_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PkceFailure:
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class PkceCredential:
+    access_token: str
+    refresh_token: str
+    expires_at: float
+    client_id: str
+    token_endpoint: str
+    revocation_endpoint: str
+    resource: str
+    user_id: str | None
+    team_id: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class CallbackCode:
+    code: str
+
+
+@dataclass(frozen=True, slots=True)
+class CallbackDenied:
+    error: str
+    description: str | None
+
+
+CallbackOutcome = CallbackCode | CallbackDenied
+
+
+class Http(Protocol):
+    def get(self, url: str, *, timeout: float) -> requests.Response: ...
+
+    def post(
+        self,
+        url: str,
+        *,
+        data: Mapping[str, str] | None = None,
+        json: Mapping[str, object] | None = None,
+        timeout: float,
+    ) -> requests.Response: ...
+
+
+class LoopbackServer(HTTPServer):
+    """The OS-assigned loopback listener the browser is sent back to. Only the response
+    carrying the pending sign-in's ``state`` settles it; anything else (a stray request, a
+    stale tab, an attacker poking the port) gets a 400 and the wait continues. A connection
+    that opens and then sends nothing is dropped after ``connection_timeout_seconds`` so it
+    cannot hold the single-threaded wait past its deadline."""
+
+    def __init__(self, expected_state: str, connection_timeout_seconds: float = 5) -> None:
+        super().__init__(("127.0.0.1", 0), _CallbackHandler)
+        self.expected_state: Final = expected_state
+        self.connection_timeout_seconds: Final = connection_timeout_seconds
+        self.outcome: CallbackOutcome | None = None
+        self.timeout = 1
+
+    @property
+    def redirect_uri(self) -> str:
+        return f"http://127.0.0.1:{self.server_address[1]}{CALLBACK_PATH}"
+
+    def get_request(self) -> tuple[socket.socket, object]:
+        accepted: Final[tuple[socket.socket, object]] = super().get_request()
+        accepted[0].settimeout(self.connection_timeout_seconds)
+        return accepted
+
+    def wait(
+        self, timeout_seconds: float, clock: Callable[[], float] = time.monotonic
+    ) -> CallbackOutcome | PkceFailure:
+        deadline: Final = clock() + timeout_seconds
+        while self.outcome is None:
+            if clock() >= deadline:
+                return PkceFailure("timed out waiting for the browser sign-in to finish")
+            self.handle_request()
+        return self.outcome
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    server: LoopbackServer  # pyright: ignore[reportIncompatibleVariableOverride]  # only ever constructed by LoopbackServer
+
+    def do_GET(self) -> None:
+        parsed: Final = urlparse(self.path)
+        if parsed.path != CALLBACK_PATH:
+            self._respond(404, "Not found.")
+            return
+        params: Final = parse_qs(parsed.query)
+        if _first(params, "state") != self.server.expected_state:
+            self._respond(400, "This response does not belong to the pending sign-in; still waiting.")
+            return
+        error: Final = _first(params, "error")
+        if error is not None:
+            self.server.outcome = CallbackDenied(error=error, description=_first(params, "error_description"))
+            self._respond(200, "Sign-in was not approved. You can close this window.")
+            return
+        code: Final = _first(params, "code")
+        if code is None:
+            self._respond(400, "The sign-in response carried no authorization code; still waiting.")
+            return
+        self.server.outcome = CallbackCode(code=code)
+        self._respond(200, "Signed in to LiteLLM. You can close this window and return to the terminal.")
+
+    def log_message(self, format: str, *args: object) -> None:
+        return
+
+    def _respond(self, status: int, text: str) -> None:
+        body: Final = text.encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "text/plain; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body)
+
+
+def _first(params: Mapping[str, Sequence[str]], key: str) -> str | None:
+    values: Final = params.get(key)
+    return values[0] if values else None
+
+
+def discover_cli_auth(base_url: str, http: Http) -> CliAuthContract | PkceFailure:
+    url: Final = f"{base_url.rstrip('/')}{CLI_AUTH_DISCOVERY_PATH}"
+    try:
+        response: Final = http.get(url, timeout=_HTTP_TIMEOUT_SECONDS)
+    except requests.RequestException as exc:
+        return PkceFailure(f"could not reach {url}: {exc}")
+    if response.status_code != 200:
+        return PkceFailure(
+            f"{url} answered {response.status_code}; this proxy version does not support `lite login --pkce`"
+        )
+    try:
+        contract: Final = CliAuthContract.model_validate(response.json())
+    except (ValueError, ValidationError) as exc:
+        return PkceFailure(f"{url} returned an unsupported discovery document: {exc}")
+    if "S256" not in contract.code_challenge_methods_supported:
+        return PkceFailure("the proxy does not support PKCE S256")
+    return contract
+
+
+class _ClientRegistration(TypedDict):
+    client_name: ReadOnly[str]
+    redirect_uris: ReadOnly[tuple[str, ...]]
+    grant_types: ReadOnly[tuple[str, ...]]
+    response_types: ReadOnly[tuple[str, ...]]
+    token_endpoint_auth_method: ReadOnly[Literal["none"]]
+
+
+def _form(**fields: str) -> Mapping[str, str]:
+    return MappingProxyType(fields)
+
+
+def register_client(contract: CliAuthContract, redirect_uri: str, http: Http) -> str | PkceFailure:
+    registration: Final[_ClientRegistration] = {
+        "client_name": _CLIENT_NAME,
+        "redirect_uris": (redirect_uri,),
+        "grant_types": ("authorization_code", "refresh_token"),
+        "response_types": ("code",),
+        "token_endpoint_auth_method": "none",
+    }
+    try:
+        response: Final = http.post(contract.registration_endpoint, json=registration, timeout=_HTTP_TIMEOUT_SECONDS)
+    except requests.RequestException as exc:
+        return PkceFailure(f"client registration failed: {exc}")
+    if response.status_code not in (200, 201):
+        return PkceFailure(f"client registration failed with {response.status_code}: {_error_detail(response)}")
+    try:
+        return _RegisteredClient.model_validate(response.json()).client_id
+    except (ValueError, ValidationError) as exc:
+        return PkceFailure(f"client registration returned an unexpected body: {exc}")
+
+
+def pkce_pair() -> tuple[str, str]:
+    verifier: Final = secrets.token_urlsafe(64)
+    digest: Final = hashlib.sha256(verifier.encode("ascii")).digest()
+    return verifier, urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+
+def authorize_url(contract: CliAuthContract, client_id: str, redirect_uri: str, state: str, code_challenge: str) -> str:
+    query: Final = urlencode(
+        _form(
+            response_type="code",
+            client_id=client_id,
+            redirect_uri=redirect_uri,
+            state=state,
+            code_challenge=code_challenge,
+            code_challenge_method="S256",
+            resource=contract.resource,
+        )
+    )
+    return f"{contract.authorization_endpoint}?{query}"
+
+
+def redeem_code(
+    contract: CliAuthContract,
+    client_id: str,
+    redirect_uri: str,
+    code: str,
+    code_verifier: str,
+    http: Http,
+    now: Callable[[], float] = time.time,
+) -> PkceCredential | PkceFailure:
+    return _token_request(
+        token_endpoint=contract.token_endpoint,
+        revocation_endpoint=contract.revocation_endpoint,
+        resource=contract.resource,
+        client_id=client_id,
+        form=_form(
+            grant_type="authorization_code",
+            code=code,
+            redirect_uri=redirect_uri,
+            client_id=client_id,
+            code_verifier=code_verifier,
+            resource=contract.resource,
+        ),
+        http=http,
+        now=now,
+    )
+
+
+def refresh_credential(
+    token_endpoint: str,
+    revocation_endpoint: str,
+    resource: str,
+    client_id: str,
+    refresh_token: str,
+    http: Http,
+    now: Callable[[], float] = time.time,
+) -> PkceCredential | PkceFailure:
+    return _token_request(
+        token_endpoint=token_endpoint,
+        revocation_endpoint=revocation_endpoint,
+        resource=resource,
+        client_id=client_id,
+        form=_form(grant_type="refresh_token", refresh_token=refresh_token, client_id=client_id, resource=resource),
+        http=http,
+        now=now,
+    )
+
+
+def _token_request(
+    token_endpoint: str,
+    revocation_endpoint: str,
+    resource: str,
+    client_id: str,
+    form: Mapping[str, str],
+    http: Http,
+    now: Callable[[], float],
+) -> PkceCredential | PkceFailure:
+    try:
+        response: Final = http.post(token_endpoint, data=form, timeout=_HTTP_TIMEOUT_SECONDS)
+    except requests.RequestException as exc:
+        return PkceFailure(f"token request failed: {exc}")
+    if response.status_code != 200:
+        return PkceFailure(f"token request failed with {response.status_code}: {_error_detail(response)}")
+    try:
+        token: Final = _TokenResponse.model_validate(response.json())
+    except (ValueError, ValidationError) as exc:
+        return PkceFailure(f"token endpoint returned an unexpected body: {exc}")
+    return PkceCredential(
+        access_token=token.access_token,
+        refresh_token=token.refresh_token,
+        expires_at=now() + token.expires_in,
+        client_id=client_id,
+        token_endpoint=token_endpoint,
+        revocation_endpoint=revocation_endpoint,
+        resource=resource,
+        user_id=token.user_id,
+        team_id=token.team_id,
+    )
+
+
+def revoke_credential(revocation_endpoint: str, client_id: str, refresh_token: str, http: Http) -> PkceFailure | None:
+    try:
+        response: Final = http.post(
+            revocation_endpoint,
+            data=_form(token=refresh_token, token_type_hint="refresh_token", client_id=client_id),
+            timeout=_HTTP_TIMEOUT_SECONDS,
+        )
+    except requests.RequestException as exc:
+        return PkceFailure(f"revocation request failed: {exc}")
+    if response.status_code != 200:
+        return PkceFailure(f"revocation failed with {response.status_code}: {_error_detail(response)}")
+    return None
+
+
+_ERROR_BODY: Final = TypeAdapter(Mapping[str, object])
+
+
+def _error_detail(response: requests.Response) -> str:
+    try:
+        body: Final = _ERROR_BODY.validate_json(response.content)
+    except ValidationError:
+        return response.text[:200]
+    return str(body.get("error_description") or body.get("error") or body.get("detail") or body)[:200]
+
+
+def run_pkce_login(
+    base_url: str,
+    http: Http,
+    open_browser: Callable[[str], object] = webbrowser.open,
+    echo: Callable[[str], None] = print,
+    timeout_seconds: float = LOGIN_TIMEOUT_SECONDS,
+) -> PkceCredential | PkceFailure:
+    contract: Final = discover_cli_auth(base_url, http)
+    if isinstance(contract, PkceFailure):
+        return contract
+    state: Final = secrets.token_urlsafe(32)
+    verifier, challenge = pkce_pair()
+    with LoopbackServer(state) as server:
+        client_id: Final = register_client(contract, server.redirect_uri, http)
+        if isinstance(client_id, PkceFailure):
+            return client_id
+        url: Final = authorize_url(contract, client_id, server.redirect_uri, state, challenge)
+        echo(f"Opening browser to: {url}")
+        echo("Approve the sign-in in your browser. Waiting...")
+        threading.Thread(target=open_browser, args=(url,), name="lite-login-browser", daemon=True).start()
+        outcome: Final = server.wait(timeout_seconds)
+    match outcome:
+        case PkceFailure():
+            return outcome
+        case CallbackDenied():
+            return PkceFailure(f"sign-in was not approved ({outcome.error}): {outcome.description or 'no details'}")
+        case CallbackCode():
+            return redeem_code(contract, client_id, server.redirect_uri, outcome.code, verifier, http)
+
+
+def pkce_token_record(base_url: str, credential: PkceCredential) -> CliTokenData:
+    record: Final[CliTokenData] = {
+        "base_url": base_url.rstrip("/"),
+        "key": credential.access_token,
+        "user_id": credential.user_id or "cli-user",
+        "user_email": "unknown",
+        "user_role": "cli",
+        "auth_header_name": "Authorization",
+        "jwt_token": "",
+        "timestamp": time.time(),
+        "expires_at": credential.expires_at,
+        "refresh_token": credential.refresh_token,
+        "client_id": credential.client_id,
+        "token_endpoint": credential.token_endpoint,
+        "revocation_endpoint": credential.revocation_endpoint,
+        "resource": credential.resource,
+        "team_id": credential.team_id,
+    }
+    return record
+
+
+def fresh_api_key(
+    token_data: Mapping[str, object],
+    save: Callable[[CliTokenData], None],
+    http: Http,
+    *,
+    reload: Callable[[], Mapping[str, object] | None],
+    now: Callable[[], float] = time.time,
+) -> str | None:
+    """The stored key, refreshed first when it is about to expire and a refresh token is
+    on file. The rotated pair is saved before the new key is returned, so a crash after
+    this point never strands the CLI with a burned refresh token. A refresh that fails
+    reads the record again, because a sibling ``lite`` process may have rotated the pair
+    first, in which case the key it saved is the live one. A record without
+    ``expires_at`` (the classic ``lite login`` credential) is returned as stored."""
+    key: Final = token_data.get("key")
+    if not isinstance(key, str) or not key:
+        return None
+    expires_at: Final = token_data.get("expires_at")
+    if not isinstance(expires_at, (int, float)):
+        return key
+    if now() < expires_at - REFRESH_LEEWAY_SECONDS:
+        return key
+    still_valid: Final = key if now() < expires_at else None
+    refresh_inputs: Final = _refresh_inputs(token_data)
+    if refresh_inputs is None:
+        return still_valid
+    refreshed: Final = refresh_credential(*refresh_inputs, http=http, now=now)
+    if isinstance(refreshed, PkceFailure):
+        return _key_rotated_by_a_sibling(reload(), token_data.get("refresh_token")) or still_valid
+    base_url: Final = token_data.get("base_url")
+    save(pkce_token_record(base_url if isinstance(base_url, str) else "", refreshed))
+    return refreshed.access_token
+
+
+def _key_rotated_by_a_sibling(record: Mapping[str, object] | None, sent_refresh_token: object) -> str | None:
+    if record is None or record.get("refresh_token") == sent_refresh_token:
+        return None
+    key: Final = record.get("key")
+    return key if isinstance(key, str) and key else None
+
+
+def _refresh_inputs(token_data: Mapping[str, object]) -> tuple[str, str, str, str, str] | None:
+    values: Final = tuple(
+        token_data.get(field)
+        for field in ("token_endpoint", "revocation_endpoint", "resource", "client_id", "refresh_token")
+    )
+    if not all(isinstance(value, str) and value for value in values):
+        return None
+    token_endpoint, revocation_endpoint, resource, client_id, refresh_token = values
+    return str(token_endpoint), str(revocation_endpoint), str(resource), str(client_id), str(refresh_token)
+
+
+def revoke_stored_credential(token_data: Mapping[str, object], http: Http) -> PkceFailure | None:
+    refresh_inputs: Final = _refresh_inputs(token_data)
+    if refresh_inputs is None:
+        return None
+    _, revocation_endpoint, _, client_id, refresh_token = refresh_inputs
+    return revoke_credential(revocation_endpoint, client_id, refresh_token, http)
diff --git a/litellm/proxy/common_utils/html_forms/native_client_consent.py b/litellm/proxy/common_utils/html_forms/native_client_consent.py
new file mode 100644
index 00000000000..dac92c4e787
--- /dev/null
+++ b/litellm/proxy/common_utils/html_forms/native_client_consent.py
@@ -0,0 +1,91 @@
+from collections.abc import Sequence
+from html import escape
+from typing import Final
+
+from litellm.constants import CLI_JWT_EXPIRATION_HOURS
+
+
+def render_native_client_consent_page(
+    *,
+    client_origin: str,
+    user_id: str,
+    teams: Sequence[tuple[str, str]],
+    flow_handle: str,
+    complete_url: str,
+) -> str:
+    """The consent page a native client's sign-in lands on: who is signed in, which
+    loopback client asked, which team the credential is attributed to, and an explicit
+    Approve or Deny that POSTs back to ``complete_url``. Every value is client- or
+    user-influenced and HTML-escaped; the flow handle travels only in the form body."""
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="referrer" content="no-referrer">
+<title>Authorize CLI access - LiteLLM</title>
+<style>
+body {{
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+    background-color: #f8fafc;
+    margin: 0;
+    padding: 20px;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    min-height: 100vh;
+    color: #1e293b;
+}}
+.container {{
+    background-color: #fff;
+    padding: 40px;
+    border-radius: 8px;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+    width: 450px;
+    max-width: 100%;
+}}
+h1 {{ margin: 0 0 16px; font-size: 24px; font-weight: 600; }}
+p {{ margin: 0 0 12px; line-height: 1.5; }}
+code {{ background: #f1f5f9; padding: 2px 6px; border-radius: 4px; }}
+label {{ display: block; margin: 16px 0 6px; font-weight: 600; }}
+select {{ width: 100%; padding: 8px; border: 1px solid #cbd5e1; border-radius: 6px; font-size: 14px; }}
+.actions {{ display: flex; gap: 12px; margin-top: 24px; }}
+button {{ flex: 1; padding: 10px; border-radius: 6px; font-size: 15px; cursor: pointer; border: 1px solid #cbd5e1; }}
+.approve {{ background: #2563eb; color: #fff; border-color: #2563eb; }}
+.deny {{ background: #fff; color: #1e293b; }}
+</style>
+</head>
+<body>
+<div class="container">
+<h1>Authorize CLI access</h1>
+<p>A command-line client at <code>{escape(client_origin)}</code> wants to call LiteLLM as <strong>{escape(user_id)}</strong>.</p>
+<p>Approving issues it a personal credential that expires within {CLI_JWT_EXPIRATION_HOURS} hours. <code>lite logout</code> stops it from being renewed. Only approve if you started this sign-in yourself.</p>
+<form method="post" action="{escape(complete_url)}">
+<input type="hidden" name="flow" value="{escape(flow_handle)}">
+{_team_field(teams)}
+<div class="actions">
+<button type="submit" name="decision" value="deny" class="deny">Deny</button>
+<button type="submit" name="decision" value="approve" class="approve">Approve</button>
+</div>
+</form>
+</div>
+</body>
+</html>
+"""
+
+
+def _team_field(teams: Sequence[tuple[str, str]]) -> str:
+    if not teams:
+        return ""
+    if len(teams) == 1:
+        team_id, team_label = teams[0]
+        return (
+            f'<input type="hidden" name="team_id" value="{escape(team_id)}">'
+            f"<p>Requests are attributed to team <strong>{escape(team_label)}</strong>.</p>"
+        )
+    options: Final = "".join(
+        f'<option value="{escape(team_id)}">{escape(team_label)}</option>' for team_id, team_label in teams
+    )
+    return (
+        f'<label for="team_id">Attribute requests to team</label><select id="team_id" name="team_id">{options}</select>'
+    )
diff --git a/litellm/proxy/management_endpoints/ui_sso.py b/litellm/proxy/management_endpoints/ui_sso.py
index 46af5dd80e1..1ebcb53fd6b 100644
--- a/litellm/proxy/management_endpoints/ui_sso.py
+++ b/litellm/proxy/management_endpoints/ui_sso.py
@@ -270,7 +270,7 @@ class _TeamRowGrants(BaseModel):
     litellm_model_table: _TeamModelAliasTable | None = None
 
 
-class _CliSsoTeamDetail(BaseModel):
+class CliSsoTeamDetail(BaseModel):
     """The per-team snapshot cached in the CLI SSO flow and echoed to the CLI on poll."""
 
     team_id: str | None = None
@@ -279,8 +279,8 @@ class _CliSsoTeamDetail(BaseModel):
     team_model_aliases: Mapping[str, str] | None = None
 
 
-_CLI_SSO_TEAM_DETAILS_ADAPTER: Final = TypeAdapter(tuple[_CliSsoTeamDetail, ...])
-_TEAMLESS_CLI_SSO_TEAM_DETAIL: Final = _CliSsoTeamDetail(team_models=())
+_CLI_SSO_TEAM_DETAILS_ADAPTER: Final = TypeAdapter(tuple[CliSsoTeamDetail, ...])
+_TEAMLESS_CLI_SSO_TEAM_DETAIL: Final = CliSsoTeamDetail(team_models=())
 
 
 class _CustomSsoCall(Protocol):
@@ -2192,10 +2192,10 @@ async def _build_cli_sso_user_defined_values(
     )
 
 
-def _cli_sso_team_detail(team_row: Mapping[str, object]) -> _CliSsoTeamDetail:
+def _cli_sso_team_detail(team_row: Mapping[str, object]) -> CliSsoTeamDetail:
     team: Final = _TeamRowGrants.model_validate(team_row)
     alias_table: Final = team.litellm_model_table
-    return _CliSsoTeamDetail(
+    return CliSsoTeamDetail(
         team_id=team.team_id,
         team_alias=team.team_alias,
         team_models=team.models,
@@ -2203,10 +2203,10 @@ def _cli_sso_team_detail(team_row: Mapping[str, object]) -> _CliSsoTeamDetail:
     )
 
 
-async def _fetch_cli_sso_team_details(
+async def fetch_cli_sso_team_details(
     prisma_client: PrismaClient,
     teams: Sequence[str],
-) -> tuple[_CliSsoTeamDetail, ...] | None:
+) -> tuple[CliSsoTeamDetail, ...] | None:
     """``None`` means the lookup itself failed, which is not the same as the user having no teams."""
     if not teams:
         return ()
@@ -2221,7 +2221,7 @@ async def _fetch_cli_sso_team_details(
     return tuple(_cli_sso_team_detail(team_row.model_dump()) for team_row in prisma_teams)
 
 
-def _cli_sso_session_teams(team_details: Sequence[_CliSsoTeamDetail]) -> list[str]:
+def _cli_sso_session_teams(team_details: Sequence[CliSsoTeamDetail]) -> list[str]:
     """The teams a login may bind to: only those whose row still exists.
 
     A team deleted out from under a membership, which is what deleting an organization
@@ -2231,7 +2231,7 @@ def _cli_sso_session_teams(team_details: Sequence[_CliSsoTeamDetail]) -> list[st
     return [detail.team_id for detail in team_details if detail.team_id is not None]
 
 
-def _selected_cli_sso_team_detail(team_details: object, team_id: str | None) -> _CliSsoTeamDetail | None:
+def selected_cli_sso_team_detail(team_details: object, team_id: str | None) -> CliSsoTeamDetail | None:
     """``None`` means the team's grants are unknown. An empty grant is a real value meaning unrestricted,
     so an unknown one must not be minted as empty."""
     if team_id is None:
@@ -2282,7 +2282,7 @@ async def _complete_cli_sso_callback_session(
     if hasattr(user_info, "teams") and user_info.teams:
         teams = user_info.teams if isinstance(user_info.teams, list) else []
 
-    team_details: Final = await _fetch_cli_sso_team_details(prisma_client=prisma_client, teams=teams)
+    team_details: Final = await fetch_cli_sso_team_details(prisma_client=prisma_client, teams=teams)
     if team_details is None:
         raise HTTPException(
             status_code=500,
@@ -2483,7 +2483,7 @@ async def cli_poll_key(
                 # If no team_id provided and user has 0 or 1 team, use first team (or None)
                 team_id = user_teams[0] if len(user_teams) > 0 else None
 
-            selected_team: Final = _selected_cli_sso_team_detail(
+            selected_team: Final = selected_cli_sso_team_detail(
                 team_details=user_team_details,
                 team_id=team_id,
             )
diff --git a/tests/test_litellm/litellm_core_utils/test_cli_token_utils.py b/tests/test_litellm/litellm_core_utils/test_cli_token_utils.py
index 27fc5eb4bd0..5593211ba6f 100644
--- a/tests/test_litellm/litellm_core_utils/test_cli_token_utils.py
+++ b/tests/test_litellm/litellm_core_utils/test_cli_token_utils.py
@@ -5,6 +5,7 @@ Unit tests for CLI token utilities
 import json
 import os
 import tempfile
+import time
 from pathlib import Path
 from unittest.mock import mock_open, patch
 
@@ -87,3 +88,29 @@ class TestCLITokenUtils:
             result = get_litellm_gateway_api_key()
 
             assert result is None
+
+
+class TestIsCliTokenFreshWithExpiresAt:
+    """A ``lite login --pkce`` record carries the proxy's own ``expires_at``, which wins
+    over the age-based guess made from ``timestamp``."""
+
+    def test_future_expiry_is_fresh(self):
+        from litellm.litellm_core_utils.cli_token_utils import is_cli_token_fresh
+
+        assert is_cli_token_fresh({"expires_at": time.time() + 3600, "timestamp": 0}) is True
+
+    def test_expiry_inside_the_buffer_is_stale(self):
+        from litellm.litellm_core_utils.cli_token_utils import is_cli_token_fresh
+
+        assert is_cli_token_fresh({"expires_at": time.time() + 100}) is False
+        assert is_cli_token_fresh({"expires_at": time.time() + 100}, buffer_hours=0) is True
+
+    def test_past_expiry_is_stale_even_with_a_fresh_timestamp(self):
+        from litellm.litellm_core_utils.cli_token_utils import is_cli_token_fresh
+
+        assert is_cli_token_fresh({"expires_at": time.time() - 1, "timestamp": time.time()}) is False
+
+    def test_non_numeric_expiry_falls_back_to_the_timestamp(self):
+        from litellm.litellm_core_utils.cli_token_utils import is_cli_token_fresh
+
+        assert is_cli_token_fresh({"expires_at": "soon", "timestamp": time.time()}) is True
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/outbound_credentials/test_session_token.py b/tests/test_litellm/proxy/_experimental/mcp_server/outbound_credentials/test_session_token.py
index a43592ebe18..36280530eac 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/outbound_credentials/test_session_token.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/outbound_credentials/test_session_token.py
@@ -212,3 +212,55 @@ def test_minted_token_repr_never_leaks_value():
     minted = mint_session_token(PRINCIPAL, KEYS, NOW)
     assert isinstance(minted, MintedSessionToken)
     assert minted.token.get_secret_value() not in repr(minted)
+
+
+def _decoded_claims(token: str, prefix: str) -> dict:
+    return jwt.decode(
+        token.removeprefix(prefix),
+        KEYS.signing_key.get_secret_value(),
+        algorithms=["HS256"],
+        options={"verify_exp": False},
+    )
+
+
+def test_mcp_principal_wire_claims_carry_no_audience_or_team_keys():
+    access_claims = _decoded_claims(_mint_access(), SESSION_TOKEN_PREFIX)
+    refresh_claims = _decoded_claims(_mint_refresh(), SESSION_REFRESH_PREFIX)
+    for claims in (access_claims, refresh_claims):
+        assert "audience" not in claims
+        assert "team_id" not in claims
+
+
+def test_legacy_signed_claims_open_with_no_audience_and_no_team():
+    opened = open_session_token(_sign_claims(_valid_claims()), KEYS, NOW)
+    assert isinstance(opened, OpenedSessionToken)
+    assert opened.principal.audience is None
+    assert opened.principal.team_id is None
+
+
+def test_proxy_api_audience_and_team_round_trip_through_the_refresh_token():
+    principal = SessionPrincipal(user_id="user-123", client_id="llm_client_abc", audience="proxy_api", team_id="team-b")
+    minted = mint_session_refresh_token(principal, KEYS, NOW)
+    assert isinstance(minted, MintedSessionToken)
+    token = minted.token.get_secret_value()
+    claims = _decoded_claims(token, SESSION_REFRESH_PREFIX)
+    assert claims["audience"] == "proxy_api"
+    assert claims["team_id"] == "team-b"
+    opened = open_session_refresh_token(token, KEYS, NOW)
+    assert isinstance(opened, OpenedSessionToken)
+    assert opened.principal == principal
+
+
+def test_signed_claims_with_an_unknown_audience_are_rejected():
+    token = _sign_claims(_valid_claims(audience="bogus"))
+    assert isinstance(open_session_token(token, KEYS, NOW), SessionMalformed)
+
+
+def test_signed_claims_with_a_non_string_team_are_rejected():
+    token = _sign_claims(_valid_claims(team_id=42))
+    assert isinstance(open_session_token(token, KEYS, NOW), SessionMalformed)
+
+
+def test_principal_rejects_an_unknown_audience_at_construction():
+    with pytest.raises(ValidationError):
+        SessionPrincipal(user_id="user-123", client_id="llm_client_abc", audience="mcp")
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
index 424b993de85..bdaf1458fb0 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
@@ -1,6 +1,9 @@
 """Tests for MCP OAuth discoverable endpoints"""
 
+import hashlib
 import json
+import time
+from base64 import urlsafe_b64encode
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
@@ -9432,3 +9435,229 @@ async def test_upstream_resource_sent_on_dcr_bridge_relay_authorize():
     query = await _authorize_query(server)
     assert query["resource"] == ["https://mcp.example.com/mcp"]
     assert query["client_id"] == ["caller-client"]
+
+
+def _s256(verifier: str) -> str:
+    return urlsafe_b64encode(hashlib.sha256(verifier.encode("ascii")).digest()).rstrip(b"=").decode("ascii")
+
+
+_NATIVE_CLIENT_MASTER_KEY = "sk-test-salt-for-LIT-5874"
+
+
+def _native_client_app(monkeypatch):
+    """The unauthenticated discoverable router served over TestClient with a signed UI session
+    cookie available, plus fakes for the two database-backed hooks the native-client flow calls."""
+    import jwt
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+
+    from litellm.proxy._experimental.mcp_server.discoverable_endpoints import router
+    from litellm.proxy._experimental.mcp_server.gateway_dcr_flow import ConsentTeam, MintedProxyCredential
+    from litellm.proxy._experimental.mcp_server.mcp_server_manager import global_mcp_server_manager
+
+    monkeypatch.setenv("LITELLM_SALT_KEY", _NATIVE_CLIENT_MASTER_KEY)
+    monkeypatch.setattr("litellm.proxy.proxy_server.master_key", _NATIVE_CLIENT_MASTER_KEY, raising=False)
+    minted = []
+
+    async def fake_mint(user_id, team_id):
+        minted.append((user_id, team_id))
+        return MintedProxyCredential(key=f"sk-cli-{len(minted)}", expires_in=3600, user_id=user_id, team_id=team_id)
+
+    async def fake_lookup(user_id):
+        return (ConsentTeam(team_id="team-a", team_alias="Team A"), ConsentTeam(team_id="team-b"))
+
+    monkeypatch.setattr(
+        "litellm.proxy._experimental.mcp_server.discoverable_endpoints.mint_proxy_credential", fake_mint
+    )
+    monkeypatch.setattr(
+        "litellm.proxy._experimental.mcp_server.discoverable_endpoints.lookup_consent_teams", fake_lookup
+    )
+    global_mcp_server_manager.registry.clear()
+    app = FastAPI()
+    app.include_router(router)
+    client = TestClient(app)
+    session_cookie = jwt.encode(
+        {"user_id": "u1", "login_method": "username_password", "exp": int(time.time()) + 600},
+        _NATIVE_CLIENT_MASTER_KEY,
+        algorithm="HS256",
+    )
+    return client, session_cookie, minted
+
+
+def _consent_flow_handle(page: str) -> str:
+    import re
+
+    match = re.search(r'name="flow" value="([^"]+)"', page)
+    assert match is not None, page
+    return match.group(1)
+
+
+def test_native_client_login_walks_discovery_consent_token_refresh_and_revoke(monkeypatch):
+    """The whole ``lite login --pkce`` server side over the real router: a Go CLI reads the versioned
+    discovery document, registers a loopback public client, the signed-in user consents to a team,
+    the code redeems for the ``lite login`` credential, the refresh token rotates, and revocation
+    kills it."""
+    from http.cookies import SimpleCookie
+    from urllib.parse import parse_qs, urlparse
+
+    client, session_cookie, minted = _native_client_app(monkeypatch)
+    redirect_uri = "http://127.0.0.1:51234/callback"
+
+    discovery = client.get("/.well-known/litellm-cli-auth")
+    assert discovery.status_code == 200
+    assert discovery.headers["cache-control"] == "no-store"
+    contract = discovery.json()
+    assert contract["contract_version"] == 1
+    assert contract["resource"] == "http://testserver"
+    assert contract["code_challenge_methods_supported"] == ["S256"]
+    assert contract["token_endpoint_auth_methods_supported"] == ["none"]
+    for endpoint in ("authorization_endpoint", "token_endpoint", "registration_endpoint", "revocation_endpoint"):
+        assert contract[endpoint].startswith("http://testserver/")
+
+    registered = client.post(
+        contract["registration_endpoint"],
+        json={
+            "client_name": "litellm-cli",
+            "redirect_uris": [redirect_uri],
+            "grant_types": ["authorization_code", "refresh_token"],
+            "response_types": ["code"],
+            "token_endpoint_auth_method": "none",
+        },
+    )
+    assert registered.status_code == 201
+    client_id = registered.json()["client_id"]
+    verifier = "v" * 43
+    authorize_params = {
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "state": "cli-state",
+        "code_challenge": _s256(verifier),
+        "code_challenge_method": "S256",
+        "resource": contract["resource"],
+    }
+
+    anonymous = client.get(contract["authorization_endpoint"], params=authorize_params, follow_redirects=False)
+    assert anonymous.status_code == 303
+    login_target = urlparse(anonymous.headers["location"])
+    assert login_target.path == "/sso/key/generate"
+    assert parse_qs(login_target.query)["return_to"][0].startswith("/authorize?")
+
+    client.cookies.set("token", session_cookie)
+    consent = client.get(contract["authorization_endpoint"], params=authorize_params, follow_redirects=False)
+    assert consent.status_code == 200
+    assert consent.headers["x-frame-options"] == "DENY"
+    assert consent.headers["cache-control"] == "no-store"
+    assert "http://127.0.0.1:51234" in consent.text
+    assert '<option value="team-b">team-b</option>' in consent.text
+    jar = SimpleCookie()
+    jar.load(consent.headers["set-cookie"])
+    assert all(morsel["httponly"] for morsel in jar.values())
+
+    denied = client.post(
+        "/authorize/complete",
+        data={"flow": _consent_flow_handle(consent.text), "decision": "deny", "team_id": "team-a"},
+        follow_redirects=False,
+    )
+    assert denied.status_code == 303
+    denied_query = parse_qs(urlparse(denied.headers["location"]).query)
+    assert denied.headers["location"].startswith(redirect_uri)
+    assert denied_query["error"] == ["access_denied"]
+    assert denied_query["state"] == ["cli-state"]
+    assert minted == []
+
+    consent_again = client.get(contract["authorization_endpoint"], params=authorize_params, follow_redirects=False)
+    approved = client.post(
+        "/authorize/complete",
+        data={"flow": _consent_flow_handle(consent_again.text), "decision": "approve", "team_id": "team-b"},
+        follow_redirects=False,
+    )
+    assert approved.status_code == 303
+    assert approved.headers["location"].startswith(redirect_uri)
+    approved_query = parse_qs(urlparse(approved.headers["location"]).query)
+    assert approved_query["state"] == ["cli-state"]
+    code = approved_query["code"][0]
+
+    token = client.post(
+        contract["token_endpoint"],
+        data={
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": redirect_uri,
+            "client_id": client_id,
+            "code_verifier": verifier,
+            "resource": contract["resource"],
+        },
+    )
+    assert token.status_code == 200, token.text
+    assert token.headers["cache-control"] == "no-store"
+    body = token.json()
+    assert body["access_token"] == "sk-cli-1"
+    assert body["token_type"] == "Bearer"
+    assert body["expires_in"] == 3600
+    assert body["user_id"] == "u1"
+    assert body["team_id"] == "team-b"
+    assert body["refresh_token"].startswith("llm_srefresh_")
+    assert minted == [("u1", "team-b")]
+
+    refreshed = client.post(
+        contract["token_endpoint"],
+        data={
+            "grant_type": "refresh_token",
+            "refresh_token": body["refresh_token"],
+            "client_id": client_id,
+            "resource": contract["resource"],
+        },
+    )
+    assert refreshed.status_code == 200, refreshed.text
+    assert refreshed.json()["access_token"] == "sk-cli-2"
+    assert refreshed.json()["team_id"] == "team-b"
+    assert refreshed.json()["refresh_token"] != body["refresh_token"]
+    assert minted == [("u1", "team-b"), ("u1", "team-b")]
+
+    revoked = client.post(
+        contract["revocation_endpoint"],
+        data={"token": refreshed.json()["refresh_token"], "token_type_hint": "refresh_token", "client_id": client_id},
+    )
+    assert revoked.status_code == 200
+    assert revoked.json() == {}
+
+    after_revoke = client.post(
+        contract["token_endpoint"],
+        data={
+            "grant_type": "refresh_token",
+            "refresh_token": refreshed.json()["refresh_token"],
+            "client_id": client_id,
+            "resource": contract["resource"],
+        },
+    )
+    assert after_revoke.status_code == 400
+    assert after_revoke.json()["error"] == "invalid_grant"
+
+    stranger = client.post(
+        contract["revocation_endpoint"], data={"token": "whatever", "client_id": "llm_dcrc_not_a_client"}
+    )
+    assert stranger.status_code == 401
+    assert stranger.json()["error"] == "invalid_client"
+
+
+def test_native_client_authorize_without_the_proxy_resource_keeps_the_mcp_flow(monkeypatch):
+    """A registered client asking for the MCP resource (or no resource) never sees the consent
+    page, so existing MCP clients are untouched by the native-client arm."""
+    client, session_cookie, minted = _native_client_app(monkeypatch)
+    registered = client.post("/register", json={"redirect_uris": ["http://127.0.0.1:51234/callback"]})
+    client.cookies.set("token", session_cookie)
+    for resource in (None, "http://testserver/mcp"):
+        params = {
+            "response_type": "code",
+            "client_id": registered.json()["client_id"],
+            "redirect_uri": "http://127.0.0.1:51234/callback",
+            "state": "s",
+            "code_challenge": _s256("v" * 43),
+            "code_challenge_method": "S256",
+            **({"resource": resource} if resource else {}),
+        }
+        response = client.get("/authorize", params=params, follow_redirects=False)
+        assert 'name="decision"' not in response.text
+        assert "team-b" not in response.text
+    assert minted == []
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_gateway_dcr_flow.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_gateway_dcr_flow.py
index cc65970a180..4e665c552f3 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_gateway_dcr_flow.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_gateway_dcr_flow.py
@@ -1,8 +1,8 @@
 """Tests for the aggregate gateway DCR flow (register, authorize, complete, token)."""
 
 import hashlib
-import html
 import json
+import re
 from base64 import urlsafe_b64encode
 from datetime import datetime, timedelta, timezone
 from http.cookies import SimpleCookie
@@ -13,12 +13,13 @@ from starlette.requests import Request
 
 from litellm.caching.caching import DualCache
 from litellm.proxy._experimental.mcp_server.gateway_dcr_flow import (
+    _AUTH_CODE_DEBUG_KEY,
     CONNECT_FLOW_COOKIE_PREFIX,
     GATEWAY_AUTH_CODE_PREFIX,
     GATEWAY_AUTH_CODE_TTL_SECONDS,
-    GATEWAY_DCR_CLIENT_ID_PREFIX,
     MANUAL_DELIVERY_AUTH_CODE_TTL_SECONDS,
-    _AUTH_CODE_DEBUG_KEY,
+    ConsentTeam,
+    MintedProxyCredential,
     _GatewayAuthCode,
     _open_sealed,
     _seal,
@@ -26,14 +27,21 @@ from litellm.proxy._experimental.mcp_server.gateway_dcr_flow import (
     aggregate_token,
     complete_connect_flow,
     is_gateway_dcr_client_id,
+    is_proxy_api_resource,
+    native_client_auth_contract,
+    native_client_authorize,
     open_gateway_dcr_client,
     register_aggregate_client,
+    revoke_refresh_token,
 )
 from litellm.proxy._experimental.mcp_server.outbound_credentials.session_credentials import (
+    SessionBearerAdmitted,
+    SessionRefreshOpened,
+    open_session_refresh_bearer,
     resolve_session_bearer,
     session_keys_from_master_key,
-    SessionBearerAdmitted,
 )
+from litellm.proxy._experimental.mcp_server.outbound_credentials.session_token import SESSION_REFRESH_PREFIX
 
 MASTER_KEY = "sk-gateway-dcr-flow-tests"
 REDIRECT_URI = "https://claude.ai/api/mcp/auth_callback"
@@ -888,9 +896,14 @@ async def test_scoped_authorize_runs_connect_page_with_sealed_scope():
     assert response.status_code == 303
     assert "/ui/connect" in response.headers["location"]
     _, cookies = _flow_cookie_from(response)
-    assert _sealed_wire_json(next(iter(cookies.values())), "", "gateway_connect_flow")["resource_server_id"] == "github-id"
+    assert (
+        _sealed_wire_json(next(iter(cookies.values())), "", "gateway_connect_flow")["resource_server_id"] == "github-id"
+    )
     code = await _finish_connect_page(response)
-    assert _sealed_wire_json(code, GATEWAY_AUTH_CODE_PREFIX, "gateway_authorization_code")["resource_server_id"] == "github-id"
+    assert (
+        _sealed_wire_json(code, GATEWAY_AUTH_CODE_PREFIX, "gateway_authorization_code")["resource_server_id"]
+        == "github-id"
+    )
     token_response = await _redeem(code, client_id)
     assert token_response.status_code == 200
     principal = _opened_principal(json.loads(token_response.body))
@@ -1039,3 +1052,542 @@ async def test_resource_resolution_is_identity_not_ip_filtered_access():
         result = resolve_scoped_resource_server(_request(), SCOPED_RESOURCE)
     assert result is not None
     manager.get_mcp_server_by_name.assert_called_once_with("github")
+
+
+LOOPBACK_REDIRECT_URI = "http://127.0.0.1:51234/callback"
+PROXY_API_RESOURCE = "https://llm.example.com"
+CONSENT_TEAMS = (ConsentTeam(team_id="team-a", team_alias="Team A"), ConsentTeam(team_id="team-b"))
+
+
+class _Minter:
+    def __init__(self, result=None):
+        self.calls = []
+        self.result = result
+
+    async def __call__(self, user_id, team_id):
+        self.calls.append((user_id, team_id))
+        if self.result is not None:
+            return self.result
+        return MintedProxyCredential(key=f"sk-cli-{user_id}", expires_in=3600, user_id=user_id, team_id=team_id)
+
+
+class _ConsentTeams:
+    def __init__(self, result=CONSENT_TEAMS):
+        self.calls = []
+        self.result = result
+
+    async def __call__(self, user_id):
+        self.calls.append(user_id)
+        return self.result
+
+
+async def _native_authorize(client_id, session_user_id="u1", lookup=None, **overrides):
+    arguments = {
+        "request": _request(query=f"resource={PROXY_API_RESOURCE}"),
+        "client_id": client_id,
+        "redirect_uri": LOOPBACK_REDIRECT_URI,
+        "state": "client-state-123",
+        "code_challenge": CODE_CHALLENGE,
+        "code_challenge_method": "S256",
+        "response_type": "code",
+        "session_user_id": session_user_id,
+        "lookup_consent_teams": lookup if lookup is not None else _ConsentTeams(),
+    }
+    return await native_client_authorize(**{**arguments, **overrides})
+
+
+def _consent_cookie_from(response) -> tuple:
+    match = re.search(r'name="flow" value="([^"]+)"', response.body.decode())
+    assert match is not None
+    handle = match.group(1)
+    cookie = SimpleCookie()
+    cookie.load(response.headers["set-cookie"])
+    name = f"{CONNECT_FLOW_COOKIE_PREFIX}{handle}"
+    return handle, {name: cookie[name].value}
+
+
+async def _complete_consent(consent, cache=None, session_user_id="u1", **overrides):
+    handle, cookies = _consent_cookie_from(consent)
+    return await complete_connect_flow(
+        request=_request("/authorize/complete", cookies=cookies, method="POST"),
+        flow_handle=handle,
+        session_user_id=session_user_id,
+        cache=cache or DualCache(),
+        **overrides,
+    )
+
+
+def _code_from(response) -> str:
+    return parse_qs(urlparse(response.headers["location"]).query)["code"][0]
+
+
+async def _native_code(client_id, team_id="team-b", cache=None) -> str:
+    approved = await _complete_consent(
+        await _native_authorize(client_id), cache=cache, decision="approve", team_id=team_id
+    )
+    assert approved.status_code == 303
+    return _code_from(approved)
+
+
+async def _redeem_native(code, client_id, minter, cache=None, resource=PROXY_API_RESOURCE, **overrides):
+    return await _redeem(
+        code,
+        client_id,
+        cache=cache,
+        redirect_uri=LOOPBACK_REDIRECT_URI,
+        resource=resource,
+        mint_proxy_credential=minter,
+        **overrides,
+    )
+
+
+async def _refresh_native(refresh_token, client_id, minter, cache, **overrides):
+    return await _redeem_native(
+        None, client_id, minter, cache=cache, grant_type="refresh_token", refresh_token=refresh_token, **overrides
+    )
+
+
+def _opened_refresh(refresh_token, client_id):
+    opened = open_session_refresh_bearer(
+        refresh_token,
+        session_keys_from_master_key(MASTER_KEY),
+        datetime.now(timezone.utc),
+        expected_client_id=client_id,
+    )
+    assert isinstance(opened, SessionRefreshOpened)
+    return opened.principal
+
+
+@pytest.mark.asyncio
+async def test_native_authorize_renders_consent_page_and_sets_flow_cookie():
+    """A native client (RFC 8707 resource = the proxy itself) gets the server-rendered consent
+    page instead of the MCP connect-page redirect: the flow handle rides only in the hidden
+    field, the sealed flow in an HttpOnly cookie, and the page can never be framed or cached."""
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    lookup = _ConsentTeams()
+    response = await _native_authorize(client_id, lookup=lookup)
+    assert response.status_code == 200
+    assert response.headers["content-type"].startswith("text/html")
+    assert response.headers["cache-control"] == "no-store"
+    assert response.headers["x-frame-options"] == "DENY"
+    assert response.headers["content-security-policy"] == "frame-ancestors 'none'"
+    assert lookup.calls == ["u1"]
+    body = response.body.decode()
+    assert "http://127.0.0.1:51234" in body
+    assert "/callback" not in body
+    assert "<strong>u1</strong>" in body
+    assert '<option value="team-a">Team A</option>' in body
+    assert '<option value="team-b">team-b</option>' in body
+    assert 'action="https://llm.example.com/authorize/complete"' in body
+    handle, cookies = _consent_cookie_from(response)
+    assert "httponly" in response.headers["set-cookie"].lower()
+    flow = _sealed_wire_json(next(iter(cookies.values())), "", "gateway_connect_flow")
+    assert flow["audience"] == "proxy_api"
+    assert flow["client_id"] == client_id
+    assert flow["redirect_uri"] == LOOPBACK_REDIRECT_URI
+    assert flow["user_id"] == "u1"
+    assert "resource_server_id" not in flow
+    assert handle not in body.replace(f'value="{handle}"', "")
+
+
+@pytest.mark.asyncio
+async def test_native_authorize_without_session_redirects_to_login_before_any_lookup():
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    lookup = _ConsentTeams()
+    response = await _native_authorize(client_id, session_user_id=None, lookup=lookup)
+    assert response.status_code == 303
+    location = response.headers["location"]
+    assert location.startswith("https://llm.example.com/sso/key/generate?return_to=")
+    assert "return_to=%2Fauthorize%3Fresource%3D" in location
+    assert lookup.calls == []
+    assert "set-cookie" not in response.headers
+
+
+@pytest.mark.asyncio
+async def test_native_authorize_validation_failures_never_reach_consent():
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    lookup = _ConsentTeams()
+    for presented_client_id, overrides, expected_error in (
+        ("llm_dcrc_bogus", {}, "invalid_client"),
+        (client_id, {"redirect_uri": "http://127.0.0.1:51235/callback"}, "invalid_request"),
+        (client_id, {"response_type": "token"}, "unsupported_response_type"),
+        (client_id, {"code_challenge": None}, "invalid_request"),
+        (client_id, {"code_challenge_method": "plain"}, "invalid_request"),
+    ):
+        response = await _native_authorize(presented_client_id, lookup=lookup, **overrides)
+        assert response.status_code == 400
+        assert json.loads(response.body)["error"] == expected_error
+        assert "set-cookie" not in response.headers
+    assert lookup.calls == []
+
+
+@pytest.mark.asyncio
+async def test_native_authorize_refuses_a_hosted_redirect_for_the_proxy_api():
+    """Registration accepts any https redirect because MCP clients can be hosted, but a
+    proxy-API grant hands out the user's personal key, so it only ever goes back to loopback."""
+    hosted = "https://evil.example/cb"
+    client_id = (await _register([hosted]))["client_id"]
+    lookup = _ConsentTeams()
+    response = await _native_authorize(client_id, redirect_uri=hosted, lookup=lookup)
+    assert response.status_code == 400
+    assert json.loads(response.body) == {
+        "error": "invalid_request",
+        "error_description": "a proxy-API grant may only redirect to a loopback address",
+    }
+    assert "set-cookie" not in response.headers
+    assert lookup.calls == []
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "failure, status, error",
+    [
+        ("unavailable", 503, "temporarily_unavailable"),
+        ("unresolvable", 500, "server_error"),
+        ("no_active_key", 403, "access_denied"),
+    ],
+)
+async def test_native_authorize_consent_lookup_failures_are_oauth_errors_without_a_flow(failure, status, error):
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    response = await _native_authorize(client_id, lookup=_ConsentTeams(failure))
+    assert response.status_code == status
+    assert json.loads(response.body)["error"] == error
+    assert "set-cookie" not in response.headers
+
+
+@pytest.mark.asyncio
+async def test_native_consent_escapes_untrusted_identifiers():
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    hostile = (ConsentTeam(team_id='t"><script>', team_alias="<b>Team</b>"), ConsentTeam(team_id="team-b"))
+    response = await _native_authorize(
+        client_id, session_user_id='<img src=x onerror="x">', lookup=_ConsentTeams(hostile)
+    )
+    body = response.body.decode()
+    assert "<script>" not in body
+    assert "<b>Team</b>" not in body
+    assert "<img" not in body
+    assert "&lt;b&gt;Team&lt;/b&gt;" in body
+    assert "&lt;img src=x onerror=&quot;x&quot;&gt;" in body
+
+
+@pytest.mark.asyncio
+async def test_native_deny_redirects_with_access_denied_and_burns_the_flow():
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    cache = DualCache()
+    consent = await _native_authorize(client_id)
+    denied = await _complete_consent(consent, cache=cache, decision="deny", team_id="team-a")
+    assert denied.status_code == 303
+    location = urlparse(denied.headers["location"])
+    assert f"{location.scheme}://{location.netloc}{location.path}" == LOOPBACK_REDIRECT_URI
+    assert parse_qs(location.query) == {"error": ["access_denied"], "state": ["client-state-123"]}
+    assert "max-age=0" in denied.headers["set-cookie"].lower()
+    retried = await _complete_consent(consent, cache=cache, decision="approve", team_id="team-a")
+    assert retried.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_native_invalid_decision_is_rejected_before_the_flow_is_consumed():
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    cache = DualCache()
+    consent = await _native_authorize(client_id)
+    bad = await _complete_consent(consent, cache=cache, decision="maybe", team_id="team-a")
+    assert bad.status_code == 400
+    assert json.loads(bad.body)["error"] == "invalid_request"
+    assert "set-cookie" not in bad.headers
+    approved = await _complete_consent(consent, cache=cache, decision="approve", team_id="team-a")
+    assert approved.status_code == 303
+    assert "code" in parse_qs(urlparse(approved.headers["location"]).query)
+
+
+@pytest.mark.asyncio
+async def test_native_complete_by_another_session_user_is_refused():
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    consent = await _native_authorize(client_id)
+    hijacked = await _complete_consent(consent, session_user_id="attacker", decision="approve", team_id="team-a")
+    assert hijacked.status_code == 403
+
+
+@pytest.mark.asyncio
+async def test_native_approve_seals_audience_and_chosen_team_into_the_code():
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    approved = await _complete_consent(await _native_authorize(client_id), decision="approve", team_id="team-b")
+    assert approved.status_code == 303
+    assert "max-age=0" in approved.headers["set-cookie"].lower()
+    location = urlparse(approved.headers["location"])
+    assert location.netloc == "127.0.0.1:51234"
+    assert location.path == "/callback"
+    query = parse_qs(location.query)
+    assert query["state"] == ["client-state-123"]
+    wire = _sealed_wire_json(query["code"][0], GATEWAY_AUTH_CODE_PREFIX, _AUTH_CODE_DEBUG_KEY)
+    assert wire["audience"] == "proxy_api"
+    assert wire["team_id"] == "team-b"
+    assert wire["user_id"] == "u1"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("team_id", [None, ""])
+async def test_native_approve_without_a_team_mints_an_unscoped_credential(team_id):
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    consent = await _native_authorize(client_id, lookup=_ConsentTeams(()))
+    assert 'name="team_id"' not in consent.body.decode()
+    approved = await _complete_consent(consent, decision="approve", team_id=team_id)
+    minter = _Minter()
+    response = await _redeem_native(_code_from(approved), client_id, minter)
+    assert response.status_code == 200
+    assert minter.calls == [("u1", None)]
+    payload = json.loads(response.body)
+    assert payload["team_id"] is None
+    assert _opened_refresh(payload["refresh_token"], client_id).team_id is None
+
+
+@pytest.mark.asyncio
+async def test_native_code_redeems_for_the_proxy_credential_and_a_rotating_refresh_token():
+    """The whole native walk on one set of artifacts: code -> CLI credential + refresh, code
+    replay refused, refresh rotates and keeps the team, the old refresh is dead."""
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    cache = DualCache()
+    minter = _Minter()
+    code = await _native_code(client_id, team_id="team-b", cache=cache)
+    response = await _redeem_native(code, client_id, minter, cache=cache)
+    assert response.status_code == 200
+    assert response.headers["cache-control"] == "no-store"
+    payload = json.loads(response.body)
+    assert minter.calls == [("u1", "team-b")]
+    assert payload["access_token"] == "sk-cli-u1"
+    assert payload["token_type"] == "Bearer"
+    assert payload["expires_in"] == 3600
+    assert payload["user_id"] == "u1"
+    assert payload["team_id"] == "team-b"
+    assert payload["refresh_token"].startswith(SESSION_REFRESH_PREFIX)
+    principal = _opened_refresh(payload["refresh_token"], client_id)
+    assert principal.audience == "proxy_api"
+    assert principal.team_id == "team-b"
+    assert principal.user_id == "u1"
+    assert principal.client_id == client_id
+
+    replayed = await _redeem_native(code, client_id, minter, cache=cache)
+    assert replayed.status_code == 400
+    assert json.loads(replayed.body)["error"] == "invalid_grant"
+    assert "already used" in json.loads(replayed.body)["error_description"]
+
+    refreshed = await _refresh_native(payload["refresh_token"], client_id, minter, cache)
+    assert refreshed.status_code == 200
+    rotated = json.loads(refreshed.body)
+    assert minter.calls[-1] == ("u1", "team-b")
+    assert rotated["access_token"] == "sk-cli-u1"
+    assert rotated["team_id"] == "team-b"
+    assert rotated["refresh_token"] != payload["refresh_token"]
+    assert _opened_refresh(rotated["refresh_token"], client_id).team_id == "team-b"
+
+    stale = await _refresh_native(payload["refresh_token"], client_id, minter, cache)
+    assert stale.status_code == 400
+    assert "already used" in json.loads(stale.body)["error_description"]
+    assert "access_token" not in json.loads(stale.body)
+
+
+@pytest.mark.asyncio
+async def test_native_refresh_is_bound_to_the_issuing_client():
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    other = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    cache = DualCache()
+    payload = json.loads(
+        (await _redeem_native(await _native_code(client_id, cache=cache), client_id, _Minter(), cache=cache)).body
+    )
+    minter = _Minter()
+    stolen = await _refresh_native(payload["refresh_token"], other, minter, cache)
+    assert stolen.status_code == 400
+    assert json.loads(stolen.body)["error"] == "invalid_grant"
+    assert minter.calls == []
+
+
+@pytest.mark.asyncio
+async def test_native_code_without_a_minter_is_refused_server_side():
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    code = await _native_code(client_id)
+    response = await _redeem(code, client_id, redirect_uri=LOOPBACK_REDIRECT_URI, resource=PROXY_API_RESOURCE)
+    assert response.status_code == 500
+    assert json.loads(response.body)["error"] == "server_error"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "failure, status, error",
+    [
+        ("not_a_member", 400, "invalid_grant"),
+        ("no_active_key", 400, "invalid_grant"),
+        ("unavailable", 503, "temporarily_unavailable"),
+        ("unresolvable", 500, "server_error"),
+    ],
+)
+async def test_native_mint_failure_maps_to_an_oauth_error_and_keeps_the_code_usable(failure, status, error):
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    cache = DualCache()
+    code = await _native_code(client_id, cache=cache)
+    failed = await _redeem_native(code, client_id, _Minter(failure), cache=cache)
+    assert failed.status_code == status
+    assert json.loads(failed.body)["error"] == error
+    assert "refresh_token" not in json.loads(failed.body)
+    retried = await _redeem_native(code, client_id, _Minter(), cache=cache)
+    assert retried.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_native_refresh_mint_failure_does_not_burn_the_refresh_token():
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    cache = DualCache()
+    payload = json.loads(
+        (await _redeem_native(await _native_code(client_id, cache=cache), client_id, _Minter(), cache=cache)).body
+    )
+    failed = await _refresh_native(payload["refresh_token"], client_id, _Minter("unavailable"), cache)
+    assert failed.status_code == 503
+    retried = await _refresh_native(payload["refresh_token"], client_id, _Minter(), cache)
+    assert retried.status_code == 200
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "resource", [PROXY_API_RESOURCE, "https://llm.example.com/", "HTTPS://LLM.EXAMPLE.COM:443", None]
+)
+async def test_native_code_accepts_the_proxy_resource_in_any_equivalent_spelling(resource):
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    response = await _redeem_native(await _native_code(client_id), client_id, _Minter(), resource=resource)
+    assert response.status_code == 200
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "resource", ["https://llm.example.com/mcp", "https://other.example.com", "http://llm.example.com", "not a url"]
+)
+async def test_native_code_refuses_a_foreign_resource_without_burning_it(resource):
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    cache = DualCache()
+    code = await _native_code(client_id, cache=cache)
+    minter = _Minter()
+    refused = await _redeem_native(code, client_id, minter, cache=cache, resource=resource)
+    assert refused.status_code == 400
+    assert json.loads(refused.body)["error"] == "invalid_target"
+    assert minter.calls == []
+    retried = await _redeem_native(code, client_id, minter, cache=cache)
+    assert retried.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_mcp_code_ignores_the_minter_and_still_yields_a_session_pair():
+    client_id = (await _register([REDIRECT_URI]))["client_id"]
+    code = await _finish_connect_page(_authorize(client_id, session_user_id="u1"))
+    minter = _Minter()
+    response = await _redeem(code, client_id, mint_proxy_credential=minter, resource=PROXY_API_RESOURCE)
+    assert response.status_code == 200
+    payload = json.loads(response.body)
+    assert minter.calls == []
+    principal = _opened_principal(payload)
+    assert principal.audience is None
+    assert principal.team_id is None
+    assert "user_id" not in payload
+
+
+@pytest.mark.asyncio
+async def test_mcp_wire_formats_carry_no_native_client_fields():
+    client_id = (await _register([REDIRECT_URI]))["client_id"]
+    handle, cookies = _flow_cookie_from(_authorize(client_id, session_user_id="u1"))
+    flow_wire = _sealed_wire_json(next(iter(cookies.values())), "", "gateway_connect_flow")
+    assert "audience" not in flow_wire
+    assert "team_id" not in flow_wire
+    completed = await complete_connect_flow(
+        request=_request("/authorize/complete", cookies=cookies, method="POST"),
+        flow_handle=handle,
+        session_user_id="u1",
+        cache=DualCache(),
+        team_id="team-a",
+        decision="approve",
+    )
+    code_wire = _sealed_wire_json(_code_from(completed), GATEWAY_AUTH_CODE_PREFIX, _AUTH_CODE_DEBUG_KEY)
+    assert "audience" not in code_wire
+    assert "team_id" not in code_wire
+
+
+@pytest.mark.asyncio
+async def test_revoke_burns_the_refresh_token_and_answers_200_for_dead_or_unknown_tokens():
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    cache = DualCache()
+    payload = json.loads(
+        (await _redeem_native(await _native_code(client_id, cache=cache), client_id, _Minter(), cache=cache)).body
+    )
+    revoked = await revoke_refresh_token(
+        token=payload["refresh_token"], client_id=client_id, master_key=MASTER_KEY, cache=cache
+    )
+    assert revoked.status_code == 200
+    assert json.loads(revoked.body) == {}
+    assert revoked.headers["cache-control"] == "no-store"
+    refreshed = await _refresh_native(payload["refresh_token"], client_id, _Minter(), cache)
+    assert refreshed.status_code == 400
+    assert json.loads(refreshed.body)["error"] == "invalid_grant"
+    again = await revoke_refresh_token(
+        token=payload["refresh_token"], client_id=client_id, master_key=MASTER_KEY, cache=cache
+    )
+    assert again.status_code == 200
+    garbage = await revoke_refresh_token(token="nonsense", client_id=client_id, master_key=MASTER_KEY, cache=cache)
+    assert garbage.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_revoke_from_another_client_leaves_the_token_usable():
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    other = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    cache = DualCache()
+    payload = json.loads(
+        (await _redeem_native(await _native_code(client_id, cache=cache), client_id, _Minter(), cache=cache)).body
+    )
+    revoked = await revoke_refresh_token(
+        token=payload["refresh_token"], client_id=other, master_key=MASTER_KEY, cache=cache
+    )
+    assert revoked.status_code == 200
+    refreshed = await _refresh_native(payload["refresh_token"], client_id, _Minter(), cache)
+    assert refreshed.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_revoke_refuses_unknown_clients_and_a_missing_master_key():
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    for bogus in ("llm_dcrc_bogus", "anything"):
+        response = await revoke_refresh_token(token="x", client_id=bogus, master_key=MASTER_KEY, cache=DualCache())
+        assert response.status_code == 401
+        assert json.loads(response.body)["error"] == "invalid_client"
+    no_key = await revoke_refresh_token(token="x", client_id=client_id, master_key=None, cache=DualCache())
+    assert no_key.status_code == 500
+    assert json.loads(no_key.body)["error"] == "server_error"
+
+
+def test_native_client_auth_contract_points_every_endpoint_at_this_proxy():
+    assert json.loads(json.dumps(native_client_auth_contract(_request("/.well-known/litellm-cli-auth")))) == {
+        "contract_version": 1,
+        "issuer": "https://llm.example.com",
+        "authorization_endpoint": "https://llm.example.com/authorize",
+        "token_endpoint": "https://llm.example.com/token",
+        "registration_endpoint": "https://llm.example.com/register",
+        "revocation_endpoint": "https://llm.example.com/revoke",
+        "resource": "https://llm.example.com",
+        "response_types_supported": ["code"],
+        "grant_types_supported": ["authorization_code", "refresh_token"],
+        "code_challenge_methods_supported": ["S256"],
+        "token_endpoint_auth_methods_supported": ["none"],
+        "revocation_endpoint_auth_methods_supported": ["none"],
+    }
+
+
+@pytest.mark.parametrize(
+    "resource, expected",
+    [
+        ("https://llm.example.com", True),
+        ("https://llm.example.com/", True),
+        ("HTTPS://LLM.EXAMPLE.COM:443", True),
+        ("https://llm.example.com/mcp", False),
+        ("http://llm.example.com", False),
+        ("https://other.example.com", False),
+        ("llm.example.com", False),
+        ("", False),
+        (None, False),
+    ],
+)
+def test_is_proxy_api_resource_matches_only_this_proxy(resource, expected):
+    assert is_proxy_api_resource(_request(), resource) is expected
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_proxy_api_credentials.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_proxy_api_credentials.py
new file mode 100644
index 00000000000..5d7c2b91046
--- /dev/null
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_proxy_api_credentials.py
@@ -0,0 +1,167 @@
+"""Tests for minting the ``lite login`` credential from a consented native-client grant."""
+
+from unittest.mock import ANY, AsyncMock
+
+import pytest
+
+from litellm.constants import CLI_JWT_EXPIRATION_HOURS
+from litellm.models.user import LiteLLM_UserTable
+from litellm.proxy._experimental.mcp_server.gateway_dcr_flow import ConsentTeam, MintedProxyCredential
+from litellm.proxy._experimental.mcp_server.proxy_api_credentials import lookup_consent_teams, mint_proxy_credential
+from litellm.proxy.auth.auth_checks import ExperimentalUIJWTToken
+from litellm.proxy.management_endpoints.ui_sso import CliSsoTeamDetail
+
+_LOAD_USER = "litellm.proxy._experimental.mcp_server.proxy_api_credentials.load_active_user_by_id"
+_FETCH_TEAMS = "litellm.proxy._experimental.mcp_server.proxy_api_credentials.fetch_cli_sso_team_details"
+_PRISMA = "litellm.proxy.proxy_server.prisma_client"
+TEAM_DETAILS = (
+    CliSsoTeamDetail(team_id="team-a", team_alias="Team A", team_models=("gpt-5.4-mini",)),
+    CliSsoTeamDetail(team_id="team-b", team_models=(), team_model_aliases={"fast": "gpt-5.4-mini"}),
+)
+
+
+def _user(**overrides) -> LiteLLM_UserTable:
+    return LiteLLM_UserTable(
+        **{
+            "user_id": "u1",
+            "user_role": "internal_user",
+            "teams": ["team-a", "team-b"],
+            "models": ["gpt-5.4"],
+            **overrides,
+        }
+    )
+
+
+def _decoded(minted: MintedProxyCredential):
+    key_object = ExperimentalUIJWTToken.get_key_object_from_ui_hash_key(minted.key)
+    assert key_object is not None
+    return key_object
+
+
+@pytest.fixture(autouse=True)
+def _salt_key(monkeypatch):
+    monkeypatch.setenv("LITELLM_SALT_KEY", "sk-proxy-api-credentials-tests")
+
+
+@pytest.fixture
+def fetch_teams(monkeypatch):
+    monkeypatch.setattr(_PRISMA, object(), raising=False)
+    fetch = AsyncMock(return_value=TEAM_DETAILS)
+    monkeypatch.setattr(_FETCH_TEAMS, fetch)
+    return fetch
+
+
+@pytest.fixture
+def load_user(monkeypatch):
+    load = AsyncMock(return_value=_user())
+    monkeypatch.setattr(_LOAD_USER, load)
+    return load
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", ["unavailable", "unresolvable", "no_active_key"])
+async def test_mint_passes_user_lookup_failures_through(failure, load_user, fetch_teams):
+    load_user.return_value = failure
+    assert await mint_proxy_credential("u1", "team-a") == failure
+    fetch_teams.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_mint_refuses_a_user_without_a_role(load_user, fetch_teams):
+    load_user.return_value = _user(user_role=None)
+    assert await mint_proxy_credential("u1", None) == "no_active_key"
+    fetch_teams.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_mint_without_a_chosen_team_never_picks_one_for_a_team_member(load_user, fetch_teams):
+    """The consent page is the only place a team gets chosen, so a grant sealed without one
+    stays unscoped on every redemption and refresh instead of drifting onto the first team."""
+    minted = await mint_proxy_credential("u1", None)
+    assert isinstance(minted, MintedProxyCredential)
+    assert minted.user_id == "u1"
+    assert minted.team_id is None
+    assert minted.expires_in == CLI_JWT_EXPIRATION_HOURS * 3600
+    load_user.assert_awaited_once_with("u1")
+    fetch_teams.assert_not_awaited()
+    decoded = _decoded(minted)
+    assert decoded.user_id == "u1"
+    assert decoded.team_id is None
+    assert decoded.team_alias is None
+    assert decoded.models == ["gpt-5.4"]
+    assert decoded.is_session_token is True
+
+
+@pytest.mark.asyncio
+async def test_mint_honors_the_consented_team(load_user, fetch_teams):
+    minted = await mint_proxy_credential("u1", "team-b")
+    assert isinstance(minted, MintedProxyCredential)
+    assert minted.team_id == "team-b"
+    decoded = _decoded(minted)
+    assert decoded.team_id == "team-b"
+    assert decoded.team_alias is None
+    assert decoded.team_models == []
+    assert decoded.team_model_aliases == {"fast": "gpt-5.4-mini"}
+
+
+@pytest.mark.asyncio
+async def test_mint_refuses_a_team_the_user_is_not_on(load_user, fetch_teams):
+    assert await mint_proxy_credential("u1", "team-c") == "not_a_member"
+    fetch_teams.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_mint_refuses_when_the_teams_grants_are_unknown(load_user, fetch_teams):
+    fetch_teams.return_value = TEAM_DETAILS[:1]
+    assert await mint_proxy_credential("u1", "team-b") == "not_a_member"
+
+
+@pytest.mark.asyncio
+async def test_mint_reports_unavailable_when_the_team_lookup_fails(load_user, fetch_teams):
+    fetch_teams.return_value = None
+    assert await mint_proxy_credential("u1", "team-a") == "unavailable"
+
+
+@pytest.mark.asyncio
+async def test_mint_reports_unavailable_without_a_database(load_user, monkeypatch):
+    monkeypatch.setattr(_PRISMA, None, raising=False)
+    assert await mint_proxy_credential("u1", "team-a") == "unavailable"
+
+
+@pytest.mark.asyncio
+async def test_mint_for_a_teamless_user_is_unscoped(load_user, fetch_teams):
+    load_user.return_value = _user(teams=[])
+    minted = await mint_proxy_credential("u1", None)
+    assert isinstance(minted, MintedProxyCredential)
+    assert minted.team_id is None
+    fetch_teams.assert_not_awaited()
+    decoded = _decoded(minted)
+    assert decoded.team_id is None
+    assert decoded.models == ["gpt-5.4"]
+
+
+@pytest.mark.asyncio
+async def test_lookup_consent_teams_lists_the_users_teams_with_aliases(load_user, fetch_teams):
+    teams = await lookup_consent_teams("u1")
+    assert teams == (ConsentTeam(team_id="team-a", team_alias="Team A"), ConsentTeam(team_id="team-b"))
+    fetch_teams.assert_awaited_once_with(ANY, ["team-a", "team-b"])
+
+
+@pytest.mark.asyncio
+async def test_lookup_consent_teams_drops_details_without_a_team_id(load_user, fetch_teams):
+    fetch_teams.return_value = (CliSsoTeamDetail(team_models=()), *TEAM_DETAILS[1:])
+    assert await lookup_consent_teams("u1") == (ConsentTeam(team_id="team-b"),)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", ["unavailable", "unresolvable", "no_active_key"])
+async def test_lookup_consent_teams_passes_user_lookup_failures_through(failure, load_user, fetch_teams):
+    load_user.return_value = failure
+    assert await lookup_consent_teams("u1") == failure
+    fetch_teams.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_lookup_consent_teams_reports_unavailable_when_details_cannot_load(load_user, fetch_teams):
+    fetch_teams.return_value = None
+    assert await lookup_consent_teams("u1") == "unavailable"
diff --git a/tests/test_litellm/proxy/client/cli/test_auth_commands.py b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
index 59048067674..dd86cba3f58 100644
--- a/tests/test_litellm/proxy/client/cli/test_auth_commands.py
+++ b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
@@ -190,19 +190,15 @@ class TestTokenUtilities:
             result = get_token_file_path()
 
             assert result == "/home/user/.litellm/token.json"
-            mock_mkdir.assert_called_once_with(exist_ok=True)
+            mock_mkdir.assert_not_called()
 
-    def test_get_token_file_path_creates_directory(self):
-        """Test that get_token_file_path creates the config directory"""
-        with (
-            patch("pathlib.Path.home") as mock_home,
-            patch("pathlib.Path.mkdir") as mock_mkdir,
-        ):
-            mock_home.return_value = Path("/home/user")
-
-            get_token_file_path()
-
-            mock_mkdir.assert_called_once_with(exist_ok=True)
+    def test_reading_the_token_never_creates_the_config_directory(self, tmp_path):
+        """Every `lite` invocation reads the token; only saving one may touch ~/.litellm"""
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            assert load_token() is None
+            assert not (tmp_path / ".litellm").exists()
+            save_token({"key": "sk-test"})
+            assert load_token() == {"key": "sk-test"}
 
     def test_save_token(self, tmp_path):
         """Test saving token data to file"""
@@ -309,7 +305,7 @@ class TestTokenUtilities:
         token_data = {"key": "test-api-key-123", "user_id": "test-user"}
 
         with patch(
-            "litellm.litellm_core_utils.cli_token_utils.load_cli_token",
+            "litellm.proxy.client.cli.commands.auth.load_token",
             return_value=token_data,
         ):
             result = get_stored_api_key()
@@ -318,7 +314,7 @@ class TestTokenUtilities:
     def test_get_stored_api_key_no_token(self):
         """Test getting stored API key when no token exists"""
         with patch(
-            "litellm.litellm_core_utils.cli_token_utils.load_cli_token",
+            "litellm.proxy.client.cli.commands.auth.load_token",
             return_value=None,
         ):
             result = get_stored_api_key()
@@ -329,7 +325,7 @@ class TestTokenUtilities:
         token_data = {"user_id": "test-user"}
 
         with patch(
-            "litellm.litellm_core_utils.cli_token_utils.load_cli_token",
+            "litellm.proxy.client.cli.commands.auth.load_token",
             return_value=token_data,
         ):
             result = get_stored_api_key()
@@ -339,7 +335,7 @@ class TestTokenUtilities:
         """Stored key is returned when expected_base_url matches stored origin"""
         token_data = {"key": "sk-prod", "base_url": "https://real-proxy.com"}
         with patch(
-            "litellm.litellm_core_utils.cli_token_utils.load_cli_token",
+            "litellm.proxy.client.cli.commands.auth.load_token",
             return_value=token_data,
         ):
             assert get_stored_api_key(expected_base_url="https://real-proxy.com") == "sk-prod"
@@ -348,7 +344,7 @@ class TestTokenUtilities:
         """Trailing slash on expected_base_url is normalised before comparison"""
         token_data = {"key": "sk-prod", "base_url": "https://real-proxy.com"}
         with patch(
-            "litellm.litellm_core_utils.cli_token_utils.load_cli_token",
+            "litellm.proxy.client.cli.commands.auth.load_token",
             return_value=token_data,
         ):
             assert get_stored_api_key(expected_base_url="https://real-proxy.com/") == "sk-prod"
@@ -357,7 +353,7 @@ class TestTokenUtilities:
         """Stored key is NOT returned when expected_base_url differs from stored origin"""
         token_data = {"key": "sk-prod", "base_url": "https://real-proxy.com"}
         with patch(
-            "litellm.litellm_core_utils.cli_token_utils.load_cli_token",
+            "litellm.proxy.client.cli.commands.auth.load_token",
             return_value=token_data,
         ):
             assert get_stored_api_key(expected_base_url="https://evil.com") is None
@@ -366,7 +362,7 @@ class TestTokenUtilities:
         """Old tokens without a base_url field are rejected when origin check is requested"""
         token_data = {"key": "sk-old-token"}
         with patch(
-            "litellm.litellm_core_utils.cli_token_utils.load_cli_token",
+            "litellm.proxy.client.cli.commands.auth.load_token",
             return_value=token_data,
         ):
             assert get_stored_api_key(expected_base_url="https://real-proxy.com") is None
@@ -1110,3 +1106,292 @@ class TestLoginConfigClaude:
         assert "could not configure Claude Code" in result.output
         assert "invalid JSON" in result.output
         assert "Authentication failed" not in result.output
+
+
+class _FakeHttpResponse:
+    def __init__(self, status_code, payload):
+        self.status_code = status_code
+        self._payload = payload
+        self.text = json.dumps(payload)
+        self.content = self.text.encode()
+
+    def json(self):
+        return self._payload
+
+
+class _FakeSession:
+    """Stands in for ``requests.Session`` so the CLI's refresh and revoke calls can be observed."""
+
+    instances = []
+
+    def __init__(self):
+        self.posts = []
+        self.response = _FakeHttpResponse(200, {})
+        _FakeSession.instances.append(self)
+
+    def post(self, url, *, data=None, json=None, timeout):
+        self.posts.append((url, data))
+        return self.response
+
+    def get(self, url, *, timeout):
+        raise AssertionError(f"unexpected GET {url}")
+
+
+PKCE_BASE_URL = "https://llm.example.com"
+PKCE_TOKEN_RESPONSE = {
+    "access_token": "sk-cli-rotated",
+    "token_type": "Bearer",
+    "expires_in": 3600,
+    "refresh_token": "llm_srefresh_rotated",
+    "user_id": "u1",
+    "team_id": "team-b",
+}
+
+
+def _pkce_record(**overrides):
+    return {
+        "base_url": PKCE_BASE_URL,
+        "key": "sk-cli-old",
+        "user_id": "u1",
+        "user_email": "unknown",
+        "user_role": "cli",
+        "auth_header_name": "Authorization",
+        "jwt_token": "",
+        "timestamp": time.time(),
+        "expires_at": time.time() + 30,
+        "refresh_token": "llm_srefresh_old",
+        "client_id": "llm_dcrc_abc",
+        "token_endpoint": f"{PKCE_BASE_URL}/token",
+        "revocation_endpoint": f"{PKCE_BASE_URL}/revoke",
+        "resource": PKCE_BASE_URL,
+        "team_id": "team-b",
+        **overrides,
+    }
+
+
+def _pkce_credential():
+    from litellm.proxy.client.cli.commands.pkce_login import PkceCredential
+
+    return PkceCredential(
+        access_token="sk-cli-fresh",
+        refresh_token="llm_srefresh_fresh",
+        expires_at=time.time() + 3600,
+        client_id="llm_dcrc_abc",
+        token_endpoint=f"{PKCE_BASE_URL}/token",
+        revocation_endpoint=f"{PKCE_BASE_URL}/revoke",
+        resource=PKCE_BASE_URL,
+        user_id="u1",
+        team_id="team-b",
+    )
+
+
+class TestPkceLoginCommand:
+    """``lite login --pkce`` swaps the proxy-mediated SSO poll for the browser PKCE flow."""
+
+    def setup_method(self):
+        self.runner = CliRunner()
+        _FakeSession.instances.clear()
+
+    def test_pkce_login_saves_the_refreshable_record_and_skips_the_sso_poll(self):
+        with (
+            patch("litellm.proxy.client.cli.commands.auth.run_pkce_login", return_value=_pkce_credential()) as run,
+            patch("litellm.proxy.client.cli.commands.auth._start_cli_sso_flow") as sso_start,
+            patch("litellm.proxy.client.cli.commands.auth.save_token") as save,
+            patch("litellm.proxy.client.cli.interface.show_commands"),
+        ):
+            result = self.runner.invoke(login, ["--pkce"], obj={"base_url": f"{PKCE_BASE_URL}/"})
+
+        assert result.exit_code == 0, result.output
+        assert "Login successful!" in result.output
+        assert "JWT Token: sk-cli-fresh..." in result.output
+        sso_start.assert_not_called()
+        assert run.call_args.args[0] == f"{PKCE_BASE_URL}/"
+        saved = save.call_args.args[0]
+        assert saved["base_url"] == PKCE_BASE_URL
+        assert saved["key"] == "sk-cli-fresh"
+        assert saved["refresh_token"] == "llm_srefresh_fresh"
+        assert saved["client_id"] == "llm_dcrc_abc"
+        assert saved["token_endpoint"] == f"{PKCE_BASE_URL}/token"
+        assert saved["revocation_endpoint"] == f"{PKCE_BASE_URL}/revoke"
+        assert saved["resource"] == PKCE_BASE_URL
+        assert saved["user_id"] == "u1"
+        assert saved["team_id"] == "team-b"
+
+    def test_pkce_login_failure_is_reported_and_nothing_is_saved(self):
+        from litellm.proxy.client.cli.commands.pkce_login import PkceFailure
+
+        with (
+            patch(
+                "litellm.proxy.client.cli.commands.auth.run_pkce_login",
+                return_value=PkceFailure("sign-in was not approved (access_denied): no details"),
+            ),
+            patch("litellm.proxy.client.cli.commands.auth.save_token") as save,
+        ):
+            result = self.runner.invoke(login, ["--pkce"], obj={"base_url": PKCE_BASE_URL})
+
+        assert result.exit_code == 0
+        assert "Authentication failed: sign-in was not approved (access_denied): no details" in result.output
+        save.assert_not_called()
+
+    def test_login_without_the_flag_never_touches_the_pkce_flow(self):
+        with (
+            patch("litellm.proxy.client.cli.commands.auth.run_pkce_login") as run,
+            patch("litellm.proxy.client.cli.commands.auth._start_cli_sso_flow", side_effect=KeyboardInterrupt),
+        ):
+            result = self.runner.invoke(login, obj={"base_url": PKCE_BASE_URL})
+
+        assert "cancelled" in result.output
+        run.assert_not_called()
+
+
+class TestPkceLogoutCommand:
+    def setup_method(self):
+        self.runner = CliRunner()
+        _FakeSession.instances.clear()
+
+    def test_logout_revokes_the_refresh_token_before_clearing(self):
+        with (
+            patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=_pkce_record()),
+            patch("litellm.proxy.client.cli.commands.auth.clear_token") as clear,
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _FakeSession),
+        ):
+            result = self.runner.invoke(logout)
+
+        assert result.exit_code == 0
+        assert result.output == "Logged out successfully. Authentication token cleared.\n"
+        clear.assert_called_once()
+        assert _FakeSession.instances[0].posts == [
+            (
+                f"{PKCE_BASE_URL}/revoke",
+                {"token": "llm_srefresh_old", "token_type_hint": "refresh_token", "client_id": "llm_dcrc_abc"},
+            )
+        ]
+
+    def test_logout_still_clears_when_revocation_fails(self):
+        class _FailingSession(_FakeSession):
+            def __init__(self):
+                super().__init__()
+                self.response = _FakeHttpResponse(503, {"error": "temporarily_unavailable"})
+
+        with (
+            patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=_pkce_record()),
+            patch("litellm.proxy.client.cli.commands.auth.clear_token") as clear,
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _FailingSession),
+        ):
+            result = self.runner.invoke(logout)
+
+        assert result.exit_code == 0
+        assert "Could not revoke the refresh token on the proxy (revocation failed with 503" in result.output
+        assert "Logged out successfully" in result.output
+        clear.assert_called_once()
+
+    def test_logout_of_a_classic_token_makes_no_request(self):
+        with (
+            patch("litellm.proxy.client.cli.commands.auth.load_token", return_value={"key": "sk-classic"}),
+            patch("litellm.proxy.client.cli.commands.auth.clear_token") as clear,
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _FakeSession),
+        ):
+            result = self.runner.invoke(logout)
+
+        assert result.output == "Logged out successfully. Authentication token cleared.\n"
+        clear.assert_called_once()
+        assert _FakeSession.instances[0].posts == []
+
+
+class TestPkcePrintToken:
+    """``lite print-token`` is Claude Code's apiKeyHelper, so a near-expiry PKCE key must be
+    refreshed silently and stdout must carry nothing but the key."""
+
+    def setup_method(self):
+        self.runner = CliRunner()
+        _FakeSession.instances.clear()
+
+    def test_print_token_refreshes_a_near_expiry_key_and_saves_the_rotation(self):
+        class _RefreshingSession(_FakeSession):
+            def __init__(self):
+                super().__init__()
+                self.response = _FakeHttpResponse(200, PKCE_TOKEN_RESPONSE)
+
+        with (
+            patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=_pkce_record()),
+            patch("litellm.proxy.client.cli.commands.auth.save_token") as save,
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _RefreshingSession),
+        ):
+            result = self.runner.invoke(print_token, obj={})
+
+        assert result.exit_code == 0, result.output
+        assert result.stdout == "sk-cli-rotated\n"
+        assert _FakeSession.instances[0].posts[0][0] == f"{PKCE_BASE_URL}/token"
+        assert _FakeSession.instances[0].posts[0][1]["refresh_token"] == "llm_srefresh_old"
+        saved = save.call_args.args[0]
+        assert saved["key"] == "sk-cli-rotated"
+        assert saved["refresh_token"] == "llm_srefresh_rotated"
+
+    def test_print_token_prints_a_fresh_pkce_key_without_a_request(self):
+        with (
+            patch(
+                "litellm.proxy.client.cli.commands.auth.load_token",
+                return_value=_pkce_record(expires_at=time.time() + 3600),
+            ),
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _FakeSession),
+        ):
+            result = self.runner.invoke(print_token, obj={})
+
+        assert result.stdout == "sk-cli-old\n"
+        assert _FakeSession.instances[0].posts == []
+
+    def test_print_token_fails_when_the_key_expired_and_refresh_is_refused(self):
+        class _RefusingSession(_FakeSession):
+            def __init__(self):
+                super().__init__()
+                self.response = _FakeHttpResponse(400, {"error": "invalid_grant"})
+
+        with (
+            patch(
+                "litellm.proxy.client.cli.commands.auth.load_token",
+                return_value=_pkce_record(expires_at=time.time() - 1),
+            ),
+            patch("litellm.proxy.client.cli.commands.auth.save_token") as save,
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _RefusingSession),
+        ):
+            result = self.runner.invoke(print_token, obj={})
+
+        assert result.exit_code == 1
+        assert result.stdout == ""
+        assert "Token expired. Run 'lite login' again." in result.output
+        save.assert_not_called()
+
+    def test_print_token_for_an_expired_classic_token_makes_no_request(self):
+        with (
+            patch(
+                "litellm.proxy.client.cli.commands.auth.load_token",
+                return_value={"key": "sk-classic", "timestamp": time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600},
+            ),
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _FakeSession),
+        ):
+            result = self.runner.invoke(print_token, obj={})
+
+        assert result.exit_code == 1
+        assert "Token expired" in result.output
+        assert _FakeSession.instances == []
+
+
+class TestGetStoredApiKeyRefresh:
+    def test_get_stored_api_key_refreshes_a_near_expiry_pkce_key(self):
+        _FakeSession.instances.clear()
+
+        class _RefreshingSession(_FakeSession):
+            def __init__(self):
+                super().__init__()
+                self.response = _FakeHttpResponse(200, PKCE_TOKEN_RESPONSE)
+
+        with (
+            patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=_pkce_record()),
+            patch("litellm.proxy.client.cli.commands.auth.save_token") as save,
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _RefreshingSession),
+        ):
+            assert get_stored_api_key(PKCE_BASE_URL) == "sk-cli-rotated"
+            assert get_stored_api_key("https://other.example.com") is None
+
+        assert save.call_count == 1
+        assert len(_FakeSession.instances) == 1
diff --git a/tests/test_litellm/proxy/client/cli/test_pkce_login.py b/tests/test_litellm/proxy/client/cli/test_pkce_login.py
new file mode 100644
index 00000000000..355d1c39d08
--- /dev/null
+++ b/tests/test_litellm/proxy/client/cli/test_pkce_login.py
@@ -0,0 +1,553 @@
+"""Tests for the ``lite login --pkce`` browser flow against a fake proxy and a real loopback listener."""
+
+import hashlib
+import json
+import re
+import socket
+import threading
+import urllib.error
+import urllib.request
+from base64 import urlsafe_b64encode
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+import requests
+
+from litellm.proxy.client.cli.commands.pkce_login import (
+    CallbackCode,
+    CallbackDenied,
+    CliAuthContract,
+    LoopbackServer,
+    PkceCredential,
+    PkceFailure,
+    _error_detail,
+    authorize_url,
+    discover_cli_auth,
+    fresh_api_key,
+    pkce_pair,
+    pkce_token_record,
+    redeem_code,
+    refresh_credential,
+    register_client,
+    revoke_credential,
+    revoke_stored_credential,
+    run_pkce_login,
+)
+
+BASE = "https://llm.example.com"
+DISCOVERY_URL = f"{BASE}/.well-known/litellm-cli-auth"
+CONTRACT_DOC = {
+    "contract_version": 1,
+    "issuer": BASE,
+    "authorization_endpoint": f"{BASE}/authorize",
+    "token_endpoint": f"{BASE}/token",
+    "registration_endpoint": f"{BASE}/register",
+    "revocation_endpoint": f"{BASE}/revoke",
+    "resource": BASE,
+    "response_types_supported": ["code"],
+    "grant_types_supported": ["authorization_code", "refresh_token"],
+    "code_challenge_methods_supported": ["S256"],
+    "token_endpoint_auth_methods_supported": ["none"],
+    "revocation_endpoint_auth_methods_supported": ["none"],
+}
+CONTRACT = CliAuthContract.model_validate(CONTRACT_DOC)
+TOKEN_JSON = {
+    "access_token": "sk-cli-new",
+    "token_type": "Bearer",
+    "expires_in": 3600,
+    "refresh_token": "llm_srefresh_new",
+    "user_id": "u1",
+    "team_id": "team-b",
+}
+STORED = {
+    "base_url": BASE,
+    "key": "sk-cli-old",
+    "expires_at": 1_000_000.0,
+    "refresh_token": "llm_srefresh_old",
+    "client_id": "llm_dcrc_abc",
+    "token_endpoint": f"{BASE}/token",
+    "revocation_endpoint": f"{BASE}/revoke",
+    "resource": BASE,
+}
+
+
+class _FakeResponse:
+    def __init__(self, status_code, payload=None, text=""):
+        self.status_code = status_code
+        self._payload = payload
+        self.text = json.dumps(payload) if payload is not None else text
+        self.content = self.text.encode()
+
+    def json(self):
+        if self._payload is None:
+            raise ValueError("not json")
+        return self._payload
+
+
+def _wire(body):
+    return None if body is None else json.loads(json.dumps(body))
+
+
+class _FakeHttp:
+    def __init__(self, routes=None):
+        self.routes = routes or {}
+        self.calls = []
+
+    def get(self, url, *, timeout):
+        self.calls.append(("GET", url, None, None))
+        return self._route("GET", url, None, None)
+
+    def post(self, url, *, data=None, json=None, timeout):
+        self.calls.append(("POST", url, data, _wire(json)))
+        return self._route("POST", url, data, json)
+
+    def _route(self, method, url, data, json):
+        handler = self.routes[(method, url)]
+        if isinstance(handler, Exception):
+            raise handler
+        return handler(data, json) if callable(handler) else handler
+
+
+def _get(url):
+    try:
+        with urllib.request.urlopen(url, timeout=5) as response:
+            return response.status, response.read().decode()
+    except urllib.error.HTTPError as error:
+        return error.code, error.read().decode()
+
+
+def _fresh(token_data, save, http, reload=lambda: None, **options):
+    return fresh_api_key(token_data, save, http, reload=reload, **options)
+
+
+def _challenge_for(verifier: str) -> str:
+    return urlsafe_b64encode(hashlib.sha256(verifier.encode("ascii")).digest()).rstrip(b"=").decode("ascii")
+
+
+def test_loopback_settles_only_on_a_code_for_the_expected_state():
+    with LoopbackServer("expected-state") as server:
+        result = {}
+        thread = threading.Thread(target=lambda: result.setdefault("outcome", server.wait(10)))
+        thread.start()
+        base = f"http://127.0.0.1:{server.server_address[1]}"
+        assert server.redirect_uri == f"{base}/callback"
+        assert _get(f"{base}/nope")[0] == 404
+        status, body = _get(f"{base}/callback?state=other&code=stolen")
+        assert status == 400
+        assert "still waiting" in body
+        status, body = _get(f"{base}/callback?state=expected-state")
+        assert status == 400
+        assert "no authorization code" in body
+        assert thread.is_alive()
+        status, body = _get(f"{base}/callback?state=expected-state&code=the-code")
+        assert status == 200
+        assert "Signed in to LiteLLM" in body
+        thread.join(5)
+    assert not thread.is_alive()
+    assert result["outcome"] == CallbackCode(code="the-code")
+
+
+def test_loopback_reports_a_denied_sign_in():
+    with LoopbackServer("expected-state") as server:
+        result = {}
+        thread = threading.Thread(target=lambda: result.setdefault("outcome", server.wait(10)))
+        thread.start()
+        base = f"http://127.0.0.1:{server.server_address[1]}"
+        status, body = _get(f"{base}/callback?state=expected-state&error=access_denied&error_description=nope")
+        assert status == 200
+        assert "not approved" in body
+        thread.join(5)
+    assert result["outcome"] == CallbackDenied(error="access_denied", description="nope")
+
+
+def test_loopback_drops_an_idle_connection_instead_of_waiting_on_it():
+    with LoopbackServer("expected-state", connection_timeout_seconds=0.2) as server:
+        result = {}
+        thread = threading.Thread(target=lambda: result.setdefault("outcome", server.wait(10)))
+        thread.start()
+        idle = socket.create_connection(server.server_address)
+        try:
+            status, body = _get(f"http://127.0.0.1:{server.server_address[1]}/callback?state=expected-state&code=c1")
+        finally:
+            idle.close()
+        assert status == 200
+        assert "Signed in to LiteLLM" in body
+        thread.join(5)
+    assert not thread.is_alive()
+    assert result["outcome"] == CallbackCode(code="c1")
+
+
+def test_loopback_wait_times_out_on_its_clock():
+    ticks = iter([0.0, 0.5, 1.5])
+    with LoopbackServer("expected-state") as server:
+        server.timeout = 0.01
+        outcome = server.wait(1.0, clock=lambda: next(ticks))
+    assert outcome == PkceFailure("timed out waiting for the browser sign-in to finish")
+
+
+def test_discover_reads_the_contract_from_the_well_known_path():
+    http = _FakeHttp({("GET", DISCOVERY_URL): _FakeResponse(200, CONTRACT_DOC)})
+    assert discover_cli_auth(f"{BASE}/", http) == CONTRACT
+
+
+@pytest.mark.parametrize(
+    "response, expected",
+    [
+        (_FakeResponse(404, text="not found"), "does not support `lite login --pkce`"),
+        (_FakeResponse(200, {**CONTRACT_DOC, "contract_version": 2}), "unsupported discovery document"),
+        (_FakeResponse(200, {"issuer": BASE}), "unsupported discovery document"),
+        (_FakeResponse(200, text="<html>"), "unsupported discovery document"),
+        (_FakeResponse(200, {**CONTRACT_DOC, "code_challenge_methods_supported": ["plain"]}), "PKCE S256"),
+        (requests.ConnectionError("refused"), "could not reach"),
+    ],
+)
+def test_discover_failures_name_the_cause(response, expected):
+    result = discover_cli_auth(BASE, _FakeHttp({("GET", DISCOVERY_URL): response}))
+    assert isinstance(result, PkceFailure)
+    assert expected in result.reason
+
+
+def test_register_sends_a_public_loopback_client_and_returns_its_id():
+    http = _FakeHttp({("POST", f"{BASE}/register"): _FakeResponse(201, {"client_id": "llm_dcrc_abc"})})
+    assert register_client(CONTRACT, "http://127.0.0.1:5/callback", http) == "llm_dcrc_abc"
+    assert http.calls == [
+        (
+            "POST",
+            f"{BASE}/register",
+            None,
+            {
+                "client_name": "litellm-cli",
+                "redirect_uris": ["http://127.0.0.1:5/callback"],
+                "grant_types": ["authorization_code", "refresh_token"],
+                "response_types": ["code"],
+                "token_endpoint_auth_method": "none",
+            },
+        )
+    ]
+
+
+@pytest.mark.parametrize(
+    "response, expected",
+    [
+        (
+            _FakeResponse(400, {"error": "invalid_redirect_uri", "error_description": "loopback only"}),
+            "400: loopback only",
+        ),
+        (_FakeResponse(201, {}), "unexpected body"),
+        (requests.ConnectionError("refused"), "registration failed"),
+    ],
+)
+def test_register_failures_name_the_cause(response, expected):
+    result = register_client(
+        CONTRACT, "http://127.0.0.1:5/callback", _FakeHttp({("POST", f"{BASE}/register"): response})
+    )
+    assert isinstance(result, PkceFailure)
+    assert expected in result.reason
+
+
+def test_pkce_pair_is_a_high_entropy_s256_pair():
+    verifier, challenge = pkce_pair()
+    assert 43 <= len(verifier) <= 128
+    assert challenge == _challenge_for(verifier)
+    assert pkce_pair()[0] != verifier
+
+
+def test_authorize_url_carries_every_oauth_parameter_and_the_proxy_resource():
+    url = authorize_url(CONTRACT, "llm_dcrc_abc", "http://127.0.0.1:5/callback", "state-1", "challenge-1")
+    parsed = urlparse(url)
+    assert f"{parsed.scheme}://{parsed.netloc}{parsed.path}" == f"{BASE}/authorize"
+    assert parse_qs(parsed.query) == {
+        "response_type": ["code"],
+        "client_id": ["llm_dcrc_abc"],
+        "redirect_uri": ["http://127.0.0.1:5/callback"],
+        "state": ["state-1"],
+        "code_challenge": ["challenge-1"],
+        "code_challenge_method": ["S256"],
+        "resource": [BASE],
+    }
+
+
+def test_redeem_code_posts_the_verifier_and_binds_the_credential_to_the_contract():
+    http = _FakeHttp({("POST", f"{BASE}/token"): _FakeResponse(200, TOKEN_JSON)})
+    credential = redeem_code(
+        CONTRACT, "llm_dcrc_abc", "http://127.0.0.1:5/callback", "the-code", "the-verifier", http, now=lambda: 100.0
+    )
+    assert credential == PkceCredential(
+        access_token="sk-cli-new",
+        refresh_token="llm_srefresh_new",
+        expires_at=3700.0,
+        client_id="llm_dcrc_abc",
+        token_endpoint=f"{BASE}/token",
+        revocation_endpoint=f"{BASE}/revoke",
+        resource=BASE,
+        user_id="u1",
+        team_id="team-b",
+    )
+    assert http.calls[0][2] == {
+        "grant_type": "authorization_code",
+        "code": "the-code",
+        "redirect_uri": "http://127.0.0.1:5/callback",
+        "client_id": "llm_dcrc_abc",
+        "code_verifier": "the-verifier",
+        "resource": BASE,
+    }
+
+
+def test_refresh_posts_the_refresh_grant_for_the_same_client_and_resource():
+    http = _FakeHttp({("POST", f"{BASE}/token"): _FakeResponse(200, TOKEN_JSON)})
+    credential = refresh_credential(
+        f"{BASE}/token", f"{BASE}/revoke", BASE, "llm_dcrc_abc", "llm_srefresh_old", http, now=lambda: 5.0
+    )
+    assert isinstance(credential, PkceCredential)
+    assert credential.expires_at == 3605.0
+    assert credential.refresh_token == "llm_srefresh_new"
+    assert http.calls[0][2] == {
+        "grant_type": "refresh_token",
+        "refresh_token": "llm_srefresh_old",
+        "client_id": "llm_dcrc_abc",
+        "resource": BASE,
+    }
+
+
+@pytest.mark.parametrize(
+    "response, expected",
+    [
+        (_FakeResponse(400, {"error": "invalid_grant", "error_description": "already used"}), "400: already used"),
+        (_FakeResponse(200, {**TOKEN_JSON, "refresh_token": ""}), "unexpected body"),
+        (_FakeResponse(200, {**TOKEN_JSON, "expires_in": 0}), "unexpected body"),
+        (_FakeResponse(200, text="<html>"), "unexpected body"),
+        (requests.ConnectionError("refused"), "token request failed"),
+    ],
+)
+def test_token_request_failures_name_the_cause(response, expected):
+    result = redeem_code(CONTRACT, "c", "r", "code", "v", _FakeHttp({("POST", f"{BASE}/token"): response}))
+    assert isinstance(result, PkceFailure)
+    assert expected in result.reason
+
+
+def test_revoke_posts_an_rfc7009_request_for_the_refresh_token():
+    http = _FakeHttp({("POST", f"{BASE}/revoke"): _FakeResponse(200, {})})
+    assert revoke_credential(f"{BASE}/revoke", "llm_dcrc_abc", "llm_srefresh_old", http) is None
+    assert http.calls == [
+        (
+            "POST",
+            f"{BASE}/revoke",
+            {"token": "llm_srefresh_old", "token_type_hint": "refresh_token", "client_id": "llm_dcrc_abc"},
+            None,
+        )
+    ]
+
+
+@pytest.mark.parametrize(
+    "response, expected",
+    [
+        (_FakeResponse(401, {"error": "invalid_client"}), "401: invalid_client"),
+        (requests.ConnectionError("refused"), "revocation request failed"),
+    ],
+)
+def test_revoke_failures_name_the_cause(response, expected):
+    result = revoke_credential(f"{BASE}/revoke", "llm_dcrc_abc", "t", _FakeHttp({("POST", f"{BASE}/revoke"): response}))
+    assert isinstance(result, PkceFailure)
+    assert expected in result.reason
+
+
+@pytest.mark.parametrize(
+    "response, expected",
+    [
+        (_FakeResponse(400, {"error": "invalid_grant", "error_description": "the code expired"}), "the code expired"),
+        (_FakeResponse(400, {"error": "invalid_grant"}), "invalid_grant"),
+        (_FakeResponse(404, {"detail": "Not Found"}), "Not Found"),
+        (_FakeResponse(502, text="<html>bad gateway</html>"), "<html>bad gateway</html>"),
+        (_FakeResponse(500, text="x" * 500), "x" * 200),
+    ],
+)
+def test_error_detail_prefers_the_oauth_description(response, expected):
+    assert _error_detail(response) == expected
+
+
+def _blocking_browser(seen, suffix):
+    seen["done"] = threading.Event()
+
+    def open_browser(url):
+        query = parse_qs(urlparse(url).query)
+        seen["authorize"] = query
+        seen["callback"] = _get(f"{query['redirect_uri'][0]}?state={query['state'][0]}&{suffix}")
+        seen["done"].set()
+
+    return open_browser
+
+
+def test_run_pkce_login_end_to_end_against_a_fake_proxy():
+    seen = {}
+
+    def register(data, json):
+        seen["register"] = json
+        return _FakeResponse(201, {"client_id": "llm_dcrc_abc"})
+
+    def token(data, json):
+        seen["token"] = data
+        return _FakeResponse(200, TOKEN_JSON)
+
+    http = _FakeHttp(
+        {
+            ("GET", DISCOVERY_URL): _FakeResponse(200, CONTRACT_DOC),
+            ("POST", f"{BASE}/register"): register,
+            ("POST", f"{BASE}/token"): token,
+        }
+    )
+    echoed = []
+    credential = run_pkce_login(
+        BASE, http, open_browser=_blocking_browser(seen, "code=the-code"), echo=echoed.append, timeout_seconds=10
+    )
+    assert isinstance(credential, PkceCredential)
+    assert credential.access_token == "sk-cli-new"
+    assert credential.refresh_token == "llm_srefresh_new"
+    assert credential.client_id == "llm_dcrc_abc"
+    assert credential.team_id == "team-b"
+    redirect_uri = seen["register"]["redirect_uris"][0]
+    assert re.fullmatch(r"http://127\.0\.0\.1:\d+/callback", redirect_uri)
+    assert seen["authorize"]["redirect_uri"] == [redirect_uri]
+    assert seen["authorize"]["client_id"] == ["llm_dcrc_abc"]
+    assert seen["authorize"]["code_challenge_method"] == ["S256"]
+    assert seen["authorize"]["resource"] == [BASE]
+    form = seen["token"]
+    assert form["code"] == "the-code"
+    assert form["redirect_uri"] == redirect_uri
+    assert form["client_id"] == "llm_dcrc_abc"
+    assert _challenge_for(form["code_verifier"]) == seen["authorize"]["code_challenge"][0]
+    assert echoed[0].startswith(f"Opening browser to: {BASE}/authorize?")
+    assert echoed[1] == "Approve the sign-in in your browser. Waiting..."
+    assert seen["done"].wait(5)
+    assert seen["callback"][0] == 200
+
+
+def test_run_pkce_login_reports_a_denied_sign_in_without_touching_the_token_endpoint():
+    seen = {}
+    http = _FakeHttp(
+        {
+            ("GET", DISCOVERY_URL): _FakeResponse(200, CONTRACT_DOC),
+            ("POST", f"{BASE}/register"): _FakeResponse(201, {"client_id": "llm_dcrc_abc"}),
+        }
+    )
+    result = run_pkce_login(
+        BASE,
+        http,
+        open_browser=_blocking_browser(seen, "error=access_denied&error_description=nope"),
+        echo=lambda _: None,
+        timeout_seconds=10,
+    )
+    assert result == PkceFailure("sign-in was not approved (access_denied): nope")
+    assert [call[1] for call in http.calls] == [DISCOVERY_URL, f"{BASE}/register"]
+
+
+def test_run_pkce_login_stops_before_the_browser_when_registration_fails():
+    opened = []
+    http = _FakeHttp(
+        {
+            ("GET", DISCOVERY_URL): _FakeResponse(200, CONTRACT_DOC),
+            ("POST", f"{BASE}/register"): _FakeResponse(400, {"error": "invalid_client_metadata"}),
+        }
+    )
+    result = run_pkce_login(BASE, http, open_browser=opened.append, echo=lambda _: None, timeout_seconds=1)
+    assert isinstance(result, PkceFailure)
+    assert "invalid_client_metadata" in result.reason
+    assert opened == []
+
+
+def test_pkce_token_record_keeps_every_refresh_input_next_to_the_key():
+    credential = PkceCredential(
+        access_token="sk-cli-new",
+        refresh_token="llm_srefresh_new",
+        expires_at=3700.0,
+        client_id="llm_dcrc_abc",
+        token_endpoint=f"{BASE}/token",
+        revocation_endpoint=f"{BASE}/revoke",
+        resource=BASE,
+        user_id=None,
+        team_id=None,
+    )
+    record = pkce_token_record(f"{BASE}/", credential)
+    assert record["base_url"] == BASE
+    assert record["key"] == "sk-cli-new"
+    assert record["user_id"] == "cli-user"
+    assert record["expires_at"] == 3700.0
+    assert record["refresh_token"] == "llm_srefresh_new"
+    assert record["client_id"] == "llm_dcrc_abc"
+    assert record["token_endpoint"] == f"{BASE}/token"
+    assert record["revocation_endpoint"] == f"{BASE}/revoke"
+    assert record["resource"] == BASE
+    assert record["team_id"] is None
+    assert record["auth_header_name"] == "Authorization"
+
+
+def test_fresh_api_key_returns_a_classic_or_still_fresh_key_without_network():
+    http = _FakeHttp()
+    saved = []
+    assert _fresh({"key": "sk-classic"}, saved.append, http) == "sk-classic"
+    assert _fresh(STORED, saved.append, http, now=lambda: 999_000.0) == "sk-cli-old"
+    assert _fresh({}, saved.append, http) is None
+    assert _fresh({"key": ""}, saved.append, http) is None
+    assert http.calls == []
+    assert saved == []
+
+
+def test_fresh_api_key_refreshes_near_expiry_and_saves_before_returning():
+    http = _FakeHttp({("POST", f"{BASE}/token"): _FakeResponse(200, TOKEN_JSON)})
+    saved = []
+    assert _fresh(STORED, saved.append, http, now=lambda: 999_950.0) == "sk-cli-new"
+    assert len(saved) == 1
+    assert saved[0]["key"] == "sk-cli-new"
+    assert saved[0]["refresh_token"] == "llm_srefresh_new"
+    assert saved[0]["expires_at"] == 999_950.0 + 3600
+    assert saved[0]["base_url"] == BASE
+    assert saved[0]["team_id"] == "team-b"
+    assert http.calls[0][2]["refresh_token"] == "llm_srefresh_old"
+
+
+def test_fresh_api_key_never_hands_out_a_rotated_key_it_could_not_save():
+    http = _FakeHttp({("POST", f"{BASE}/token"): _FakeResponse(200, TOKEN_JSON)})
+
+    def save(_record):
+        raise OSError("disk full")
+
+    with pytest.raises(OSError):
+        _fresh(STORED, save, http, now=lambda: 999_950.0)
+
+
+def test_fresh_api_key_falls_back_to_the_old_key_only_while_it_is_still_valid():
+    failing = _FakeHttp({("POST", f"{BASE}/token"): _FakeResponse(503, {"error": "temporarily_unavailable"})})
+    saved = []
+    assert _fresh(STORED, saved.append, failing, now=lambda: 999_950.0) == "sk-cli-old"
+    assert _fresh(STORED, saved.append, failing, now=lambda: 1_000_001.0) is None
+    assert saved == []
+
+
+def test_fresh_api_key_uses_a_sibling_rotation_when_its_own_refresh_loses_the_race():
+    rotated = {**STORED, "key": "sk-cli-sibling", "refresh_token": "llm_srefresh_sibling", "expires_at": 1_003_600.0}
+    http = _FakeHttp({("POST", f"{BASE}/token"): _FakeResponse(400, {"error": "invalid_grant"})})
+    saved = []
+    assert _fresh(STORED, saved.append, http, reload=lambda: rotated, now=lambda: 999_950.0) == "sk-cli-sibling"
+    assert _fresh(STORED, saved.append, http, reload=lambda: rotated, now=lambda: 1_000_001.0) == "sk-cli-sibling"
+    assert _fresh(STORED, saved.append, http, reload=lambda: STORED, now=lambda: 1_000_001.0) is None
+    assert _fresh(STORED, saved.append, http, reload=lambda: None, now=lambda: 1_000_001.0) is None
+    assert saved == []
+
+
+def test_fresh_api_key_without_refresh_inputs_expires_like_a_classic_key():
+    http = _FakeHttp()
+    no_refresh = {key: value for key, value in STORED.items() if key != "refresh_token"}
+    assert _fresh(no_refresh, lambda _: None, http, now=lambda: 999_950.0) == "sk-cli-old"
+    assert _fresh(no_refresh, lambda _: None, http, now=lambda: 1_000_001.0) is None
+    assert http.calls == []
+
+
+def test_revoke_stored_credential_revokes_only_pkce_records():
+    http = _FakeHttp({("POST", f"{BASE}/revoke"): _FakeResponse(200, {})})
+    assert revoke_stored_credential({"key": "sk-classic"}, http) is None
+    assert http.calls == []
+    assert revoke_stored_credential(STORED, http) is None
+    assert http.calls[0][2] == {
+        "token": "llm_srefresh_old",
+        "token_type_hint": "refresh_token",
+        "client_id": "llm_dcrc_abc",
+    }
diff --git a/tests/test_litellm/proxy/common_utils/html_forms/test_native_client_consent.py b/tests/test_litellm/proxy/common_utils/html_forms/test_native_client_consent.py
new file mode 100644
index 00000000000..600e421c176
--- /dev/null
+++ b/tests/test_litellm/proxy/common_utils/html_forms/test_native_client_consent.py
@@ -0,0 +1,70 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../../../"))
+
+from litellm.constants import CLI_JWT_EXPIRATION_HOURS
+from litellm.proxy.common_utils.html_forms.native_client_consent import render_native_client_consent_page
+
+
+def _render(teams=(), **overrides) -> str:
+    arguments = {
+        "client_origin": "http://127.0.0.1:51234",
+        "user_id": "u1",
+        "teams": teams,
+        "flow_handle": "handle-123",
+        "complete_url": "https://llm.example.com/authorize/complete",
+    }
+    return render_native_client_consent_page(**{**arguments, **overrides})
+
+
+def test_consent_page_posts_the_flow_handle_and_both_decisions_to_the_complete_url():
+    page = _render()
+    assert '<meta name="referrer" content="no-referrer">' in page
+    assert '<form method="post" action="https://llm.example.com/authorize/complete">' in page
+    assert '<input type="hidden" name="flow" value="handle-123">' in page
+    assert '<button type="submit" name="decision" value="deny"' in page
+    assert '<button type="submit" name="decision" value="approve"' in page
+    assert "<code>http://127.0.0.1:51234</code>" in page
+    assert "<strong>u1</strong>" in page
+    assert 'name="team_id"' not in page
+
+
+def test_consent_page_pins_a_single_team_without_a_chooser():
+    page = _render(teams=(("team-a", "Team A"),))
+    assert '<input type="hidden" name="team_id" value="team-a">' in page
+    assert "<strong>Team A</strong>" in page
+    assert "<select" not in page
+
+
+def test_consent_page_offers_a_chooser_for_several_teams():
+    page = _render(teams=(("team-a", "Team A"), ("team-b", "team-b")))
+    assert '<select id="team_id" name="team_id">' in page
+    assert '<option value="team-a">Team A</option>' in page
+    assert '<option value="team-b">team-b</option>' in page
+    assert 'type="hidden" name="team_id"' not in page
+
+
+def test_consent_page_escapes_every_untrusted_value():
+    page = _render(
+        teams=(('t"><script>', "<b>x</b>"),),
+        client_origin="http://127.0.0.1:1/<svg>",
+        user_id='<img src=x onerror="y">',
+        flow_handle='h" onmouseover="z',
+        complete_url="https://llm.example.com/authorize/complete?x=<y>",
+    )
+    assert "<script>" not in page
+    assert "<b>x</b>" not in page
+    assert "<svg>" not in page
+    assert "<img" not in page
+    assert 'onmouseover="z' not in page
+    assert "?x=<y>" not in page
+    assert "&lt;b&gt;x&lt;/b&gt;" in page
+    assert 'value="h&quot; onmouseover=&quot;z"' in page
+
+
+def test_consent_page_promises_only_what_logout_can_deliver():
+    page = _render()
+    assert f"expires within {CLI_JWT_EXPIRATION_HOURS} hours" in page
+    assert "<code>lite logout</code> stops it from being renewed" in page
+    assert "revoked" not in page
diff --git a/tests/test_litellm/proxy/management_endpoints/test_ui_sso.py b/tests/test_litellm/proxy/management_endpoints/test_ui_sso.py
index b83b862d6b8..80b7e25e07d 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_ui_sso.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_ui_sso.py
@@ -3266,7 +3266,7 @@ class TestCLIKeyRegenerationFlow:
         too, otherwise alias lookup at request time is a substring match on a string.
         """
         from litellm.proxy.management_endpoints.ui_sso import (
-            _fetch_cli_sso_team_details,
+            fetch_cli_sso_team_details,
         )
 
         team_row = MagicMock()
@@ -3285,7 +3285,7 @@ class TestCLIKeyRegenerationFlow:
         prisma_client = MagicMock()
         prisma_client.db.litellm_teamtable.find_many = find_many
 
-        details = await _fetch_cli_sso_team_details(
+        details = await fetch_cli_sso_team_details(
             prisma_client=prisma_client, teams=["team-a"]
         )
 
@@ -3308,7 +3308,7 @@ class TestCLIKeyRegenerationFlow:
         real empty answer means the team rows are genuinely gone.
         """
         from litellm.proxy.management_endpoints.ui_sso import (
-            _fetch_cli_sso_team_details,
+            fetch_cli_sso_team_details,
         )
 
         failing_client = MagicMock()
@@ -3316,7 +3316,7 @@ class TestCLIKeyRegenerationFlow:
             side_effect=Exception("connection reset")
         )
         assert (
-            await _fetch_cli_sso_team_details(
+            await fetch_cli_sso_team_details(
                 prisma_client=failing_client, teams=["team-a"]
             )
             is None
@@ -3325,7 +3325,7 @@ class TestCLIKeyRegenerationFlow:
         empty_client = MagicMock()
         empty_client.db.litellm_teamtable.find_many = AsyncMock(return_value=[])
         assert (
-            await _fetch_cli_sso_team_details(
+            await fetch_cli_sso_team_details(
                 prisma_client=empty_client, teams=["team-a"]
             )
             == ()
@@ -8124,7 +8124,7 @@ async def test_cli_completion_persists_assertion_under_db_user_id():
             AsyncMock(return_value=user_info),
         ),
         patch(
-            "litellm.proxy.management_endpoints.ui_sso._fetch_cli_sso_team_details",
+            "litellm.proxy.management_endpoints.ui_sso.fetch_cli_sso_team_details",
             AsyncMock(return_value=[]),
         ),
         patch(
@@ -8202,11 +8202,11 @@ async def test_cli_completion_drops_teams_whose_rows_no_longer_exist():
     would be refused with no way for the user to recover.
     """
     from litellm.proxy.management_endpoints.ui_sso import (
-        _CliSsoTeamDetail,
+        CliSsoTeamDetail,
         _complete_cli_sso_callback_session,
     )
 
-    live_detail = _CliSsoTeamDetail(
+    live_detail = CliSsoTeamDetail(
         team_id="team-live", team_alias="Live", team_models=("gpt-4.1",)
     )
     flow = {}
@@ -8216,7 +8216,7 @@ async def test_cli_completion_drops_teams_whose_rows_no_longer_exist():
             AsyncMock(return_value=_cli_callback_user_info(["team-live", "team-deleted"])),
         ),
         patch(
-            "litellm.proxy.management_endpoints.ui_sso._fetch_cli_sso_team_details",
+            "litellm.proxy.management_endpoints.ui_sso.fetch_cli_sso_team_details",
             AsyncMock(return_value=(live_detail,)),
         ),
         patch(
@@ -8254,7 +8254,7 @@ async def test_cli_completion_fails_the_login_when_team_lookup_fails():
             AsyncMock(return_value=_cli_callback_user_info(["team-live"])),
         ),
         patch(
-            "litellm.proxy.management_endpoints.ui_sso._fetch_cli_sso_team_details",
+            "litellm.proxy.management_endpoints.ui_sso.fetch_cli_sso_team_details",
             AsyncMock(return_value=None),
         ),
         patch(

From 5f6d22e7921de56e62524d2052e194300d80d2ee Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 04:16:22 -0700
Subject: [PATCH 13/35] Map cache_control_injection_points to OpenAI
 prompt_cache_breakpoint on GPT-5.6+ targets

When the resolved deployment is provider openai and the model is GPT-5.6 or
newer, the cache control hook now writes prompt_cache_breakpoint on the
targeted content block and sets prompt_cache_options to explicit mode unless
the caller already passed one. The /v1/messages bridges carry the marker
through (the Responses bridge moves a marked system prompt into a developer
message, since top-level instructions cannot hold one). Breakpoint counting
and the stand-down check recognise both marker kinds, and client breakpoints
already present in messages are no longer subtracted from the cap twice.

Fixes #37509
---
 .../anthropic_cache_control_hook.py           | 216 ++++++--
 .../prompt_templates/common_utils.py          |  15 +-
 .../adapters/transformation.py                |  10 +
 .../responses_adapters/transformation.py      |  49 +-
 .../anthropic_cache_control_hook.py           |   4 +-
 litellm/types/llms/anthropic.py               |   4 +
 litellm/types/llms/openai.py                  |  11 +
 .../test_anthropic_cache_control_hook.py      | 477 +++++++++++++++++-
 ...al_pass_through_adapters_transformation.py |  56 ++
 .../test_handler_output_config_passthrough.py |   7 +
 .../test_responses_adapters_transformation.py | 152 ++++++
 .../chat/test_openai_gpt_transformation.py    |  45 ++
 .../test_openai_responses_transformation.py   |  58 +++
 13 files changed, 1052 insertions(+), 52 deletions(-)

diff --git a/litellm/integrations/anthropic_cache_control_hook.py b/litellm/integrations/anthropic_cache_control_hook.py
index 4df6fce74c0..05e2a37a230 100644
--- a/litellm/integrations/anthropic_cache_control_hook.py
+++ b/litellm/integrations/anthropic_cache_control_hook.py
@@ -10,17 +10,29 @@ Supported for both `v1/chat/completions` (via the prompt-management hook) and
 """
 
 import copy
+import re
+from collections.abc import Iterable, Mapping, Sequence
 from typing import TYPE_CHECKING, Any, Final, cast
 
 from litellm._logging import verbose_logger
 from litellm.integrations.custom_logger import CustomLogger
 from litellm.integrations.custom_prompt_management import CustomPromptManagement
 from litellm.integrations.prompt_management_base import PromptManagementClient
+from litellm.litellm_core_utils.prompt_templates.common_utils import (
+    with_prompt_cache_breakpoint,
+)
 from litellm.types.integrations.anthropic_cache_control_hook import (
     CacheControlInjectionPoint,
     CacheControlMessageInjectionPoint,
 )
-from litellm.types.llms.openai import AllMessageValues, ChatCompletionCachedContent
+from litellm.types.llms.anthropic import AnthropicSystemMessageContent
+from litellm.types.llms.openai import (
+    AllMessageValues,
+    ChatCompletionCachedContent,
+    ChatCompletionTextObject,
+    PromptCacheBreakpoint,
+    PromptCacheOptions,
+)
 from litellm.types.prompts.init_prompts import PromptSpec
 from litellm.types.utils import StandardCallbackDynamicParams
 
@@ -34,6 +46,27 @@ else:
 # breakpoints: "A maximum of 4 blocks with cache_control may be provided."
 MAX_CACHE_CONTROL_BLOCKS: Final = 4
 
+CACHE_BREAKPOINT_KEYS: Final = ("cache_control", "prompt_cache_breakpoint")
+OPENAI_PROMPT_CACHE_BREAKPOINT_MIN_GPT_VERSION: Final = (5, 6)
+_GPT_VERSION_PATTERN: Final = re.compile(r"^gpt-(\d+)(?:\.(\d+))?")
+OPENAI_PROMPT_CACHE_BREAKPOINT_BLOCK_TYPES: Final = frozenset({"text", "image", "image_url", "file", "input_audio"})
+
+
+def supports_openai_prompt_cache_breakpoint(model: str) -> bool:
+    version_match: Final = _GPT_VERSION_PATTERN.match(model.rsplit("/", 1)[-1].lower())
+    if version_match is None:
+        return False
+    version: Final = (int(version_match.group(1)), int(version_match.group(2) or 0))
+    return version >= OPENAI_PROMPT_CACHE_BREAKPOINT_MIN_GPT_VERSION
+
+
+def _carries_cache_breakpoint(block: object) -> bool:
+    return isinstance(block, dict) and any(block.get(key) is not None for key in CACHE_BREAKPOINT_KEYS)
+
+
+def _accepts_prompt_cache_breakpoint(block: object) -> bool:
+    return isinstance(block, dict) and block.get("type") in OPENAI_PROMPT_CACHE_BREAKPOINT_BLOCK_TYPES
+
 
 class AnthropicCacheControlHook(CustomPromptManagement):
     def get_chat_completion_prompt(
@@ -83,11 +116,21 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         # limit, so reserve a slot for it here to leave room.
         reserved_blocks: Final = 1 if any(p.get("location") == "tool_config" for p in remaining_points) else 0
 
+        openai_dialect: Final = AnthropicCacheControlHook._targets_openai_prompt_cache_breakpoint(
+            model, injection_points[0].get("_litellm_provider")
+        )
+        breakpoints_before: Final = AnthropicCacheControlHook._count_request_cache_breakpoints(processed_messages)
         processed_messages = self._apply_message_injections(
             points=message_points,
             messages=processed_messages,
             max_blocks=MAX_CACHE_CONTROL_BLOCKS - reserved_blocks,
+            openai_dialect=openai_dialect,
         )
+        if (
+            openai_dialect
+            and AnthropicCacheControlHook._count_request_cache_breakpoints(processed_messages) > breakpoints_before
+        ):
+            non_default_params.setdefault("prompt_cache_options", PromptCacheOptions(mode="explicit"))
 
         # Pass through non-message injection points for provider-specific handling
         if remaining_points:
@@ -97,11 +140,36 @@ class AnthropicCacheControlHook(CustomPromptManagement):
 
         return model, processed_messages, non_default_params
 
+    @staticmethod
+    def _targets_openai_prompt_cache_breakpoint(model: str | None, custom_llm_provider: str | None) -> bool:
+        if model is None or not supports_openai_prompt_cache_breakpoint(model):
+            return False
+        return (custom_llm_provider or AnthropicCacheControlHook._resolve_provider(model)) == "openai"
+
+    @staticmethod
+    def _resolve_provider(model: str) -> str | None:
+        from litellm.exceptions import BadRequestError
+        from litellm.litellm_core_utils.get_llm_provider_logic import get_llm_provider
+
+        try:
+            _, provider, _, _ = get_llm_provider(model=model)
+        except BadRequestError:
+            return None
+        return provider
+
+    @staticmethod
+    def _count_request_cache_breakpoints(messages: Iterable[object], system: object = None) -> int:
+        system_blocks: Final = (
+            sum(1 for block in system if _carries_cache_breakpoint(block)) if isinstance(system, list) else 0
+        )
+        return system_blocks + sum(AnthropicCacheControlHook._count_cache_control_blocks(msg) for msg in messages)
+
     @staticmethod
     def _apply_message_injections(
         points: list[CacheControlMessageInjectionPoint],
         messages: list[AllMessageValues],
         max_blocks: int,
+        openai_dialect: bool = False,
     ) -> list[AllMessageValues]:
         """Apply message-level cache control injection points in order.
 
@@ -112,7 +180,7 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         ``max_blocks`` is reached. Injection points are honored in config order,
         so earlier points win when slots are scarce.
         """
-        used_blocks = sum(AnthropicCacheControlHook._count_cache_control_blocks(msg) for msg in messages)
+        used_blocks = AnthropicCacheControlHook._count_request_cache_breakpoints(messages)
 
         limit_reached = False
         for point in points:
@@ -134,16 +202,17 @@ class AnthropicCacheControlHook(CustomPromptManagement):
                     continue
 
                 messages[target_index] = AnthropicCacheControlHook._safe_insert_cache_control_in_message(
-                    messages[target_index], control
+                    messages[target_index], control, openai_dialect
                 )
-                used_blocks += 1
+                if AnthropicCacheControlHook._message_has_cache_control(messages[target_index]):
+                    used_blocks += 1
 
             if limit_reached:
                 break
 
         if limit_reached:
             verbose_logger.warning(
-                "AnthropicCacheControlHook: Reached the Anthropic limit of %s cache_control blocks. Skipping further injection.",
+                "AnthropicCacheControlHook: Reached the provider limit of %s cache breakpoints. Skipping further injection.",
                 MAX_CACHE_CONTROL_BLOCKS,
             )
 
@@ -189,16 +258,13 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         return []
 
     @staticmethod
-    def _count_cache_control_blocks(message: AllMessageValues) -> int:
-        """Count cache_control breakpoints on a message (message + content level)."""
-        count = 0
-        if message.get("cache_control") is not None:
-            count += 1
+    def _count_cache_control_blocks(message: object) -> int:
+        if not isinstance(message, dict):
+            return 0
+        count = 1 if _carries_cache_breakpoint(message) else 0
         content: Final = message.get("content")
         if isinstance(content, list):
-            for block in content:
-                if isinstance(block, dict) and block.get("cache_control") is not None:
-                    count += 1
+            count += sum(1 for block in content if _carries_cache_breakpoint(block))
         return count
 
     @staticmethod
@@ -208,7 +274,7 @@ class AnthropicCacheControlHook(CustomPromptManagement):
 
     @staticmethod
     def _safe_insert_cache_control_in_message(
-        message: AllMessageValues, control: ChatCompletionCachedContent
+        message: AllMessageValues, control: ChatCompletionCachedContent, openai_dialect: bool = False
     ) -> AllMessageValues:
         """
         Safe way to insert cache control in a message
@@ -221,6 +287,9 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         Per Anthropic's API specification, when using multiple content blocks,
         only the last content block can have cache_control.
         """
+        if openai_dialect:
+            return AnthropicCacheControlHook._insert_prompt_cache_breakpoint_in_message(message)
+
         message_content: Final = message.get("content", None)
 
         # 1. if string, insert cache control in the message
@@ -232,11 +301,43 @@ class AnthropicCacheControlHook(CustomPromptManagement):
                 message_content[-1]["cache_control"] = control
         return message
 
+    @staticmethod
+    def _insert_prompt_cache_breakpoint_in_message(message: AllMessageValues) -> AllMessageValues:
+        if message.get("role") == "assistant":
+            return message
+        message_content: Final = message.get("content", None)
+        if isinstance(message_content, str):
+            marked: Final = copy.copy(message)
+            marked["content"] = [
+                with_prompt_cache_breakpoint(
+                    ChatCompletionTextObject(type="text", text=message_content), PromptCacheBreakpoint(mode="explicit")
+                )
+            ]
+            return marked
+        if isinstance(message_content, list):
+            with_prompt_cache_breakpoint(
+                next((block for block in reversed(message_content) if _accepts_prompt_cache_breakpoint(block)), None),
+                PromptCacheBreakpoint(mode="explicit"),
+            )
+        return message
+
+    @staticmethod
+    def _system_block_with_breakpoint(
+        block: Mapping[str, object], control: ChatCompletionCachedContent, openai_dialect: bool
+    ) -> Mapping[str, object]:
+        marker: Final = (
+            ("prompt_cache_breakpoint", PromptCacheBreakpoint(mode="explicit"))
+            if openai_dialect
+            else ("cache_control", control)
+        )
+        return {**block, marker[0]: marker[1]}
+
     @staticmethod
     def apply_to_anthropic_messages_request(
         messages: list[dict],
         system: str | list | None,
         injection_points: list[CacheControlInjectionPoint],
+        openai_dialect: bool = False,
     ) -> tuple[list[dict], str | list | None, list[CacheControlInjectionPoint]]:
         """Apply cache control injection for the Anthropic-native v1/messages endpoint.
 
@@ -265,27 +366,27 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         reserved_blocks: Final = 1 if any(p.get("location") == "tool_config" for p in remaining_points) else 0
         max_blocks: Final = MAX_CACHE_CONTROL_BLOCKS - reserved_blocks
 
-        used_blocks = sum(
-            AnthropicCacheControlHook._count_cache_control_blocks(cast(AllMessageValues, msg))
-            for msg in processed_messages
-        )
-        if isinstance(processed_system, list):
-            used_blocks += sum(
-                1 for b in processed_system if isinstance(b, dict) and b.get("cache_control") is not None
-            )
+        message_blocks: Final = AnthropicCacheControlHook._count_request_cache_breakpoints(processed_messages)
+        system_blocks = AnthropicCacheControlHook._count_request_cache_breakpoints((), processed_system)
 
-        if system_points and processed_system is not None and used_blocks < max_blocks:
+        if system_points and processed_system is not None and message_blocks + system_blocks < max_blocks:
             system_already_has_cc: Final = isinstance(processed_system, list) and any(
-                isinstance(b, dict) and b.get("cache_control") is not None for b in processed_system
+                _carries_cache_breakpoint(b) for b in processed_system
             )
             if not system_already_has_cc:
                 control: Final = system_points[0].get("control") or ChatCompletionCachedContent(type="ephemeral")
                 if isinstance(processed_system, str):
-                    processed_system = [{"type": "text", "text": processed_system, "cache_control": control}]
-                    used_blocks += 1
+                    processed_system = [
+                        AnthropicCacheControlHook._system_block_with_breakpoint(
+                            AnthropicSystemMessageContent(type="text", text=processed_system), control, openai_dialect
+                        )
+                    ]
+                    system_blocks += 1
                 elif len(processed_system) > 0 and isinstance(processed_system[-1], dict):
-                    processed_system[-1] = {**processed_system[-1], "cache_control": control}
-                    used_blocks += 1
+                    processed_system[-1] = AnthropicCacheControlHook._system_block_with_breakpoint(
+                        processed_system[-1], control, openai_dialect
+                    )
+                    system_blocks += 1
 
         for i, msg in enumerate(processed_messages):
             content = msg.get("content")
@@ -295,7 +396,8 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         processed_messages = AnthropicCacheControlHook._apply_message_injections(
             points=message_points,
             messages=cast(list[AllMessageValues], processed_messages),
-            max_blocks=max_blocks - used_blocks,
+            max_blocks=max_blocks - system_blocks,
+            openai_dialect=openai_dialect,
         )
 
         return processed_messages, processed_system, remaining_points
@@ -315,17 +417,43 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         return ChatCompletionCachedContent(type="ephemeral")
 
     @staticmethod
-    def _stamped_as_judged(points: list[CacheControlInjectionPoint]) -> list[dict[str, object]]:
+    def _stamped_as_judged(points: Sequence[CacheControlInjectionPoint]) -> Sequence[Mapping[str, object]]:
         """Mark written-back points as having passed the client cache_control judgment.
 
         Builds copies because config-owned point dicts are shared across
         requests; mutating them would leak the stamp into future requests.
         """
-        return [{**point, "_litellm_judged": True} for point in points]
+        return AnthropicCacheControlHook._stamped(points, "_litellm_judged", True)
+
+    @staticmethod
+    def _judged_configured_points(
+        points: Sequence[CacheControlInjectionPoint],
+        messages: list[AllMessageValues],
+        tools: list[object] | None,
+        model: str,
+        custom_llm_provider: str | None,
+    ) -> Sequence[Mapping[str, object]] | None:
+        if AnthropicCacheControlHook._should_stand_down(points, messages, None, tools):
+            return None
+        return AnthropicCacheControlHook._stamped_with_provider(points, model, custom_llm_provider)
+
+    @staticmethod
+    def _stamped_with_provider(
+        points: Sequence[CacheControlInjectionPoint], model: str, custom_llm_provider: str | None
+    ) -> Sequence[Mapping[str, object]]:
+        if custom_llm_provider is None or not supports_openai_prompt_cache_breakpoint(model):
+            return points
+        return AnthropicCacheControlHook._stamped(points, "_litellm_provider", custom_llm_provider)
+
+    @staticmethod
+    def _stamped(
+        points: Sequence[CacheControlInjectionPoint], key: str, value: object
+    ) -> Sequence[Mapping[str, object]]:
+        return [{**point, key: value} for point in points]
 
     @staticmethod
     def _should_stand_down(
-        points: list[CacheControlInjectionPoint],
+        points: Sequence[CacheControlInjectionPoint],
         messages: list[AllMessageValues],
         system: str | list | None,
         tools: list | None,
@@ -359,11 +487,8 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         carry the mark either at the top level (Anthropic shape) or nested under
         ``function`` (OpenAI shape); the Anthropic chat transform accepts both.
         """
-        if any(AnthropicCacheControlHook._count_cache_control_blocks(msg) for msg in messages):
+        if AnthropicCacheControlHook._count_request_cache_breakpoints(messages, system) > 0:
             return True
-        if isinstance(system, list):
-            if any(isinstance(block, dict) and block.get("cache_control") is not None for block in system):
-                return True
         if tools is not None:
             return any(
                 isinstance(tool, dict)
@@ -452,10 +577,13 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         unchanged.
         """
         if non_default_params.get("cache_control_injection_points"):
-            if AnthropicCacheControlHook._should_stand_down(
-                non_default_params["cache_control_injection_points"], messages, None, tools
-            ):
+            judged: Final = AnthropicCacheControlHook._judged_configured_points(
+                non_default_params["cache_control_injection_points"], messages, tools, model, custom_llm_provider
+            )
+            if judged is None:
                 non_default_params.pop("cache_control_injection_points")
+            else:
+                non_default_params["cache_control_injection_points"] = judged
             return
         points: Final = AnthropicCacheControlHook.get_default_injection_points(
             messages=messages,
@@ -513,11 +641,21 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         if not injection_points:
             return messages, system
 
+        openai_dialect: Final = AnthropicCacheControlHook._targets_openai_prompt_cache_breakpoint(
+            model, custom_llm_provider
+        )
+        breakpoints_before: Final = AnthropicCacheControlHook._count_request_cache_breakpoints(messages, system)
         messages, system, remaining = AnthropicCacheControlHook.apply_to_anthropic_messages_request(
             messages=messages,
             system=system,
             injection_points=injection_points,
+            openai_dialect=openai_dialect,
         )
+        if (
+            openai_dialect
+            and AnthropicCacheControlHook._count_request_cache_breakpoints(messages, system) > breakpoints_before
+        ):
+            kwargs.setdefault("prompt_cache_options", PromptCacheOptions(mode="explicit"))
         if remaining:
             kwargs["cache_control_injection_points"] = AnthropicCacheControlHook._stamped_as_judged(remaining)
         return messages, system
diff --git a/litellm/litellm_core_utils/prompt_templates/common_utils.py b/litellm/litellm_core_utils/prompt_templates/common_utils.py
index e4c1c9fc5cf..5904a14e79f 100644
--- a/litellm/litellm_core_utils/prompt_templates/common_utils.py
+++ b/litellm/litellm_core_utils/prompt_templates/common_utils.py
@@ -10,7 +10,7 @@ from collections.abc import Iterable, Mapping, Sequence
 from itertools import groupby
 from os import PathLike
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Final, Literal, cast
+from typing import TYPE_CHECKING, Any, Final, Literal, TypeVar, cast
 
 from openai.types.chat.chat_completion_custom_tool_param import (
     CustomFormatGrammar,
@@ -1325,6 +1325,19 @@ def check_is_function_call(logging_obj: "LoggingClass") -> bool:
     return False
 
 
+_MarkedT = TypeVar("_MarkedT")
+
+
+def _set_prompt_cache_breakpoint(target: object, marker: object) -> None:
+    if marker is not None and isinstance(target, dict):
+        target["prompt_cache_breakpoint"] = marker
+
+
+def with_prompt_cache_breakpoint(target: _MarkedT, marker: object) -> _MarkedT:
+    _set_prompt_cache_breakpoint(target, marker)
+    return target
+
+
 def filter_value_from_dict(dictionary: dict, key: str, depth: int = 0) -> Any:
     """
     Filters a value from a dictionary
diff --git a/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py b/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py
index e45414b4a73..2ee50e2a55b 100644
--- a/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py
+++ b/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py
@@ -61,6 +61,7 @@ from openai.types.chat.chat_completion_chunk import Choice as OpenAIStreamingCho
 
 from litellm.litellm_core_utils.prompt_templates.common_utils import (
     parse_tool_call_arguments,
+    with_prompt_cache_breakpoint,
 )
 from litellm.litellm_core_utils.prompt_templates.factory import (
     THOUGHT_SIGNATURE_SEPARATOR,
@@ -308,6 +309,11 @@ class LiteLLMAnthropicMessagesAdapter:
                 # Fallback for non-dict objects (shouldn't happen in practice)
                 cast(dict[str, object], target)["cache_control"] = cache_control
 
+    @staticmethod
+    def _add_prompt_cache_breakpoint_if_present(source: object, target: object) -> None:
+        if isinstance(source, dict) and "prompt_cache_breakpoint" in source:
+            with_prompt_cache_breakpoint(target, source["prompt_cache_breakpoint"])
+
     def translatable_anthropic_params(self) -> list[str]:
         """
         Which anthropic params, we need to translate to the openai format.
@@ -368,6 +374,7 @@ class LiteLLMAnthropicMessagesAdapter:
                         if content.get("type") == "text":
                             text_obj = ChatCompletionTextObject(type="text", text=content.get("text", ""))
                             self._add_cache_control_if_applicable(content, text_obj, model)
+                            self._add_prompt_cache_breakpoint_if_present(content, text_obj)
                             new_user_content_list.append(text_obj)
                         elif content.get("type") == "image":
                             # Convert Anthropic image format to OpenAI format
@@ -378,6 +385,7 @@ class LiteLLMAnthropicMessagesAdapter:
                                 image_url_obj = ChatCompletionImageUrlObject(url=openai_image_url)
                                 image_obj = ChatCompletionImageObject(type="image_url", image_url=image_url_obj)
                                 self._add_cache_control_if_applicable(content, image_obj, model)
+                                self._add_prompt_cache_breakpoint_if_present(content, image_obj)
                                 new_user_content_list.append(image_obj)
                         elif content.get("type") == "document":
                             # Convert Anthropic document format (PDF, etc.) to OpenAI format
@@ -869,6 +877,7 @@ class LiteLLMAnthropicMessagesAdapter:
                 continue
             text_obj = ChatCompletionTextObject(type="text", text=text)
             self._add_cache_control_if_applicable(block, text_obj, model)
+            self._add_prompt_cache_breakpoint_if_present(block, text_obj)
             text_parts.append(text_obj)
         return ChatCompletionSystemMessage(role="system", content=text_parts) if text_parts else None
 
@@ -900,6 +909,7 @@ class LiteLLMAnthropicMessagesAdapter:
                         "text": block.get("text", ""),
                     }
                     self._add_cache_control_if_applicable(block, text_block, model_name)
+                    self._add_prompt_cache_breakpoint_if_present(block, text_block)
                     openai_system_content.append(text_block)
             if openai_system_content:
                 new_messages.insert(
diff --git a/litellm/llms/anthropic/experimental_pass_through/responses_adapters/transformation.py b/litellm/llms/anthropic/experimental_pass_through/responses_adapters/transformation.py
index 21a8cb9501e..18f33c63e4d 100644
--- a/litellm/llms/anthropic/experimental_pass_through/responses_adapters/transformation.py
+++ b/litellm/llms/anthropic/experimental_pass_through/responses_adapters/transformation.py
@@ -12,6 +12,7 @@ from typing import Any, Final, cast
 from litellm.litellm_core_utils.prompt_templates.common_utils import (
     TOOL_RESULT_IMAGE_BOUNDARY,
     TOOL_RESULT_IMAGE_PLACEHOLDER,
+    with_prompt_cache_breakpoint,
 )
 from litellm.litellm_core_utils.reasoning_effort_utils import (
     reasoning_effort_from_thinking_budget,
@@ -82,7 +83,7 @@ class LiteLLMAnthropicToResponsesAPIAdapter:
     @staticmethod
     def _translate_midturn_system_content_to_responses(
         content: str | Iterable[AnthropicSystemMessageContent],
-    ) -> list[dict[str, str]]:  # mutable-ok: API message payload
+    ) -> list[dict[str, object]]:  # mutable-ok: API message payload
         """Convert in-sequence system content to Responses input-text parts."""
         if isinstance(content, str):
             return (
@@ -91,7 +92,9 @@ class LiteLLMAnthropicToResponsesAPIAdapter:
         if not isinstance(content, list):
             return []  # mutable-ok: API message payload
         return [  # mutable-ok: API message payload
-            {"type": "input_text", "text": text}  # mutable-ok: API message payload
+            with_prompt_cache_breakpoint(
+                {"type": "input_text", "text": text}, block.get("prompt_cache_breakpoint")
+            )  # mutable-ok: API message payload
             for block in content
             if isinstance(block, dict) and block.get("type") == "text" and (text := block.get("text"))  # pyright: ignore[reportUnnecessaryIsInstance]  # untrusted client payload
         ]
@@ -146,11 +149,20 @@ class LiteLLMAnthropicToResponsesAPIAdapter:
                             continue
                         btype = block.get("type")
                         if btype == "text":
-                            user_parts.append({"type": "input_text", "text": block.get("text", "")})
+                            user_parts.append(
+                                with_prompt_cache_breakpoint(
+                                    {"type": "input_text", "text": block.get("text", "")},
+                                    block.get("prompt_cache_breakpoint"),
+                                )
+                            )
                         elif btype == "image":
                             url = self._translate_anthropic_image_source_to_url(cast(dict, block.get("source", {})))
                             if url:
-                                user_parts.append({"type": "input_image", "image_url": url})
+                                user_parts.append(
+                                    with_prompt_cache_breakpoint(
+                                        {"type": "input_image", "image_url": url}, block.get("prompt_cache_breakpoint")
+                                    )
+                                )
                         elif btype == "tool_result":
                             tool_use_id = block.get("tool_use_id", "")
                             inner = block.get("content")
@@ -376,19 +388,36 @@ class LiteLLMAnthropicToResponsesAPIAdapter:
             anthropic_request["messages"],
         )
 
+        input_items: Final = self.translate_messages_to_responses_input(messages_list)
+        system: Final = anthropic_request.get("system")
+        developer_parts: Final = (
+            self._translate_midturn_system_content_to_responses(system)
+            if isinstance(system, list)
+            and any(isinstance(block, dict) and block.get("prompt_cache_breakpoint") is not None for block in system)
+            else ()
+        )
+        if developer_parts:
+            input_items.insert(
+                0,
+                {  # mutable-ok: API message payload
+                    "type": "message",
+                    "role": "developer",
+                    "content": developer_parts,
+                },
+            )
+
         responses_kwargs: Final[dict[str, Any]] = {
             "model": model,
-            "input": self.translate_messages_to_responses_input(messages_list),
+            "input": input_items,
         }
 
-        # system -> instructions
-        system: Final = anthropic_request.get("system")
-        if system:
+        if system and not developer_parts:
             if isinstance(system, str):
                 responses_kwargs["instructions"] = system
             elif isinstance(system, list):
-                text_parts = [b.get("text", "") for b in system if isinstance(b, dict) and b.get("type") == "text"]
-                responses_kwargs["instructions"] = "\n".join(filter(None, text_parts))
+                responses_kwargs["instructions"] = "\n".join(
+                    filter(None, (b.get("text", "") for b in system if isinstance(b, dict) and b.get("type") == "text"))
+                )
 
         # max_tokens -> max_output_tokens
         max_tokens: Final = anthropic_request.get("max_tokens")
diff --git a/litellm/types/integrations/anthropic_cache_control_hook.py b/litellm/types/integrations/anthropic_cache_control_hook.py
index da9b26ebbd8..3b3dcf5c86d 100644
--- a/litellm/types/integrations/anthropic_cache_control_hook.py
+++ b/litellm/types/integrations/anthropic_cache_control_hook.py
@@ -1,6 +1,6 @@
 from typing import Literal
 
-from typing_extensions import NotRequired, TypedDict
+from typing_extensions import NotRequired, ReadOnly, TypedDict
 
 from litellm.types.llms.openai import ChatCompletionCachedContent
 
@@ -13,6 +13,7 @@ class CacheControlMessageInjectionPoint(TypedDict):
     index: int | str | None  # Optional: target by specific index
     control: ChatCompletionCachedContent | None
     _litellm_judged: NotRequired[bool]  # Internal: written back by litellm once the client cache_control judgment ran
+    _litellm_provider: NotRequired[ReadOnly[str]]
 
 
 class CacheControlToolConfigInjectionPoint(TypedDict):
@@ -21,6 +22,7 @@ class CacheControlToolConfigInjectionPoint(TypedDict):
     location: Literal["tool_config"]
     control: ChatCompletionCachedContent | None
     _litellm_judged: NotRequired[bool]  # Internal: written back by litellm once the client cache_control judgment ran
+    _litellm_provider: NotRequired[ReadOnly[str]]
 
 
 CacheControlInjectionPoint = CacheControlMessageInjectionPoint | CacheControlToolConfigInjectionPoint
diff --git a/litellm/types/llms/anthropic.py b/litellm/types/llms/anthropic.py
index 5179210f942..43e1d3a4e11 100644
--- a/litellm/types/llms/anthropic.py
+++ b/litellm/types/llms/anthropic.py
@@ -9,6 +9,7 @@ from .openai import (
     ChatCompletionCachedContent,
     ChatCompletionRedactedThinkingBlock,
     ChatCompletionThinkingBlock,
+    PromptCacheBreakpoint,
 )
 
 
@@ -201,6 +202,7 @@ class AnthropicMessagesTextParam(TypedDict, total=False):
     type: Required[Literal["text"]]
     text: Required[str]
     cache_control: dict | ChatCompletionCachedContent | None
+    prompt_cache_breakpoint: ReadOnly[PromptCacheBreakpoint]
 
 
 class AnthropicMessagesToolUseParam(TypedDict, total=False):
@@ -261,6 +263,7 @@ class AnthropicMessagesImageParam(TypedDict, total=False):
     type: Required[Literal["image"]]
     source: Required[AnthropicContentParamSource | AnthropicContentParamSourceFileId | AnthropicContentParamSourceUrl]
     cache_control: dict | ChatCompletionCachedContent | None
+    prompt_cache_breakpoint: ReadOnly[PromptCacheBreakpoint]
 
 
 class CitationsObject(TypedDict):
@@ -347,6 +350,7 @@ class AnthropicSystemMessageContent(TypedDict, total=False):
     type: str
     text: str
     cache_control: dict | ChatCompletionCachedContent | None
+    prompt_cache_breakpoint: ReadOnly[PromptCacheBreakpoint]
 
 
 class AnthropicMessagesSystemMessageParam(TypedDict, total=False):
diff --git a/litellm/types/llms/openai.py b/litellm/types/llms/openai.py
index edfc50c99f6..4c7f416ab8c 100644
--- a/litellm/types/llms/openai.py
+++ b/litellm/types/llms/openai.py
@@ -71,6 +71,7 @@ from pydantic import (
 )
 from typing_extensions import (
     NotRequired,
+    ReadOnly,
     Required,
     TypedDict,
     override,
@@ -510,6 +511,15 @@ class ChatCompletionCachedContent(TypedDict):
     ttl: NotRequired[Literal["5m", "1h"]]
 
 
+class PromptCacheBreakpoint(TypedDict):
+    mode: ReadOnly[Literal["explicit"]]
+
+
+class PromptCacheOptions(TypedDict, total=False):
+    mode: ReadOnly[Literal["implicit", "explicit"]]
+    ttl: ReadOnly[Literal["30m"]]
+
+
 class ChatCompletionThinkingBlock(TypedDict, total=False):
     type: Required[Literal["thinking"]]
     thinking: str
@@ -1148,6 +1158,7 @@ class ResponsesAPIOptionalRequestParams(TypedDict, total=False):
     max_tool_calls: int | None
     prompt_cache_key: str | None
     prompt_cache_retention: str | None
+    prompt_cache_options: ReadOnly[PromptCacheOptions | None]
     stream_options: ResponsesAPIStreamOptions | None
     top_logprobs: int | None
     partial_images: int | None  # Number of partial images to generate (1-3) for streaming image generation
diff --git a/tests/test_litellm/integrations/test_anthropic_cache_control_hook.py b/tests/test_litellm/integrations/test_anthropic_cache_control_hook.py
index cc43a424419..04876b9bf12 100644
--- a/tests/test_litellm/integrations/test_anthropic_cache_control_hook.py
+++ b/tests/test_litellm/integrations/test_anthropic_cache_control_hook.py
@@ -14,7 +14,10 @@ import pytest
 
 sys.path.insert(0, os.path.abspath("../.."))  # Adds the parent directory to the system-path
 import litellm
-from litellm.integrations.anthropic_cache_control_hook import AnthropicCacheControlHook
+from litellm.integrations.anthropic_cache_control_hook import (
+    AnthropicCacheControlHook,
+    supports_openai_prompt_cache_breakpoint,
+)
 from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
 from litellm.types.llms.openai import AllMessageValues
 from litellm.types.utils import StandardCallbackDynamicParams
@@ -1996,3 +1999,475 @@ class TestAnthropicPromptCachingEnvVars:
         """An unparseable TTL must fall back to Anthropic's 5m default, never reach the provider verbatim."""
         _, ttl = self._import_litellm_with_env({"LITELLM_ANTHROPIC_PROMPT_CACHING_TTL": value})
         assert ttl is None
+
+
+def _contains_key(value, key) -> bool:
+    if isinstance(value, dict):
+        return key in value or any(_contains_key(v, key) for v in value.values())
+    if isinstance(value, list):
+        return any(_contains_key(v, key) for v in value)
+    return False
+
+
+class TestOpenAIPromptCacheBreakpoint:
+    """OpenAI GPT-5.6+ targets get content-block `prompt_cache_breakpoint` markers and a
+    request-level `prompt_cache_options` instead of Anthropic `cache_control` (#37509)."""
+
+    EXPLICIT = {"mode": "explicit"}
+    SYSTEM_POINT = [{"location": "message", "role": "system"}]
+
+    @staticmethod
+    def _inject(messages, system, kwargs, model="openai/gpt-5.6", custom_llm_provider=None):
+        return AnthropicCacheControlHook.maybe_inject_cache_control(
+            copy.deepcopy(messages),
+            copy.deepcopy(system),
+            kwargs,
+            model=model,
+            custom_llm_provider=custom_llm_provider,
+        )
+
+    @staticmethod
+    def _chat(messages, params, model="openai/gpt-5.6"):
+        return AnthropicCacheControlHook().get_chat_completion_prompt(
+            model=model,
+            messages=copy.deepcopy(messages),
+            non_default_params=params,
+            prompt_id=None,
+            prompt_variables=None,
+            dynamic_callback_params={},
+        )
+
+    @pytest.mark.parametrize(
+        "model,expected",
+        [
+            ("gpt-5.6", True),
+            ("openai/gpt-5.6", True),
+            ("gpt-5.6-sol", True),
+            ("gpt-5.6-luna", True),
+            ("gpt-5.7", True),
+            ("gpt-6", True),
+            ("GPT-5.6", True),
+            ("gpt-5.5", False),
+            ("gpt-5", False),
+            ("gpt-5-chat-latest", False),
+            ("gpt-4.1", False),
+            ("o3", False),
+            ("claude-sonnet-4-5", False),
+        ],
+    )
+    def test_model_support_truth_table(self, model, expected):
+        assert supports_openai_prompt_cache_breakpoint(model) is expected
+
+    @pytest.mark.parametrize(
+        "model,provider,expected",
+        [
+            ("openai/gpt-5.6", None, True),
+            ("gpt-5.6", None, True),
+            ("gpt-5.6", "openai", True),
+            ("gpt-5.6", "azure", False),
+            ("azure/gpt-5.6", None, False),
+            ("openai/gpt-4.1", None, False),
+            ("anthropic/claude-sonnet-4-5", None, False),
+            ("no-provider-can-route-this-model", None, False),
+            (None, "openai", False),
+        ],
+    )
+    def test_dialect_resolution(self, model, provider, expected):
+        assert AnthropicCacheControlHook._targets_openai_prompt_cache_breakpoint(model, provider) is expected
+
+    def test_count_covers_both_marker_kinds(self):
+        message = {
+            "role": "user",
+            "cache_control": {"type": "ephemeral"},
+            "content": [
+                {"type": "text", "text": "a", "prompt_cache_breakpoint": self.EXPLICIT},
+                {"type": "text", "text": "b", "cache_control": {"type": "ephemeral"}},
+                {"type": "text", "text": "c"},
+            ],
+        }
+        assert AnthropicCacheControlHook._count_cache_control_blocks(message) == 3
+
+    def test_v1_messages_string_system_gets_block_breakpoint(self):
+        kwargs = {"cache_control_injection_points": copy.deepcopy(self.SYSTEM_POINT)}
+        messages, system = self._inject([{"role": "user", "content": "hi"}], "sys", kwargs)
+        assert system == [{"type": "text", "text": "sys", "prompt_cache_breakpoint": self.EXPLICIT}]
+        assert messages == [{"role": "user", "content": [{"type": "text", "text": "hi"}]}]
+        assert kwargs == {"prompt_cache_options": self.EXPLICIT}
+        assert not _contains_key(system, "cache_control")
+
+    def test_v1_messages_list_system_marks_last_block_only(self):
+        kwargs = {"cache_control_injection_points": copy.deepcopy(self.SYSTEM_POINT)}
+        system = [{"type": "text", "text": "a"}, {"type": "text", "text": "b"}]
+        _, result_system = self._inject([{"role": "user", "content": "hi"}], system, kwargs)
+        assert result_system == [
+            {"type": "text", "text": "a"},
+            {"type": "text", "text": "b", "prompt_cache_breakpoint": self.EXPLICIT},
+        ]
+        assert kwargs["prompt_cache_options"] == self.EXPLICIT
+
+    def test_v1_messages_targets_by_role(self):
+        messages = [
+            {"role": "user", "content": [{"type": "text", "text": "first"}, {"type": "text", "text": "second"}]},
+            {"role": "assistant", "content": [{"type": "text", "text": "reply"}]},
+            {"role": "user", "content": "last"},
+        ]
+        kwargs = {"cache_control_injection_points": [{"location": "message", "role": "user"}]}
+        result, _ = self._inject(messages, None, kwargs)
+        assert result[0]["content"] == [
+            {"type": "text", "text": "first"},
+            {"type": "text", "text": "second", "prompt_cache_breakpoint": self.EXPLICIT},
+        ]
+        assert result[1] == messages[1]
+        assert result[2]["content"] == [{"type": "text", "text": "last", "prompt_cache_breakpoint": self.EXPLICIT}]
+        assert kwargs["prompt_cache_options"] == self.EXPLICIT
+
+    def test_v1_messages_targets_by_index(self):
+        messages = [
+            {"role": "user", "content": [{"type": "text", "text": "first"}]},
+            {"role": "assistant", "content": [{"type": "text", "text": "reply"}]},
+            {"role": "user", "content": [{"type": "text", "text": "last"}]},
+        ]
+        kwargs = {"cache_control_injection_points": [{"location": "message", "index": -1}]}
+        result, _ = self._inject(messages, None, kwargs)
+        assert result[:2] == messages[:2]
+        assert result[2]["content"] == [{"type": "text", "text": "last", "prompt_cache_breakpoint": self.EXPLICIT}]
+
+    def test_v1_messages_control_field_is_ignored(self):
+        ttl_control = {"type": "ephemeral", "ttl": "1h"}
+        kwargs = {
+            "cache_control_injection_points": [
+                {"location": "message", "role": "system", "control": ttl_control},
+                {"location": "message", "index": -1, "control": ttl_control},
+            ]
+        }
+        messages, system = self._inject([{"role": "user", "content": "hi"}], "sys", kwargs)
+        assert system[0]["prompt_cache_breakpoint"] == self.EXPLICIT
+        assert messages[0]["content"][-1]["prompt_cache_breakpoint"] == self.EXPLICIT
+        assert not _contains_key(system, "cache_control")
+        assert not _contains_key(messages, "cache_control")
+
+    def test_v1_messages_keeps_caller_prompt_cache_options(self):
+        caller_options = {"mode": "explicit", "ttl": "30m"}
+        kwargs = {
+            "cache_control_injection_points": copy.deepcopy(self.SYSTEM_POINT),
+            "prompt_cache_options": dict(caller_options),
+        }
+        _, system = self._inject([{"role": "user", "content": "hi"}], "sys", kwargs)
+        assert system[0]["prompt_cache_breakpoint"] == self.EXPLICIT
+        assert kwargs["prompt_cache_options"] == caller_options
+
+    def test_v1_messages_no_prompt_cache_options_when_nothing_injected(self):
+        kwargs = {"cache_control_injection_points": copy.deepcopy(self.SYSTEM_POINT)}
+        messages, system = self._inject([{"role": "user", "content": "hi"}], None, kwargs)
+        assert system is None
+        assert "prompt_cache_options" not in kwargs
+        assert not _contains_key(messages, "prompt_cache_breakpoint")
+
+    def test_v1_messages_anthropic_target_unchanged(self):
+        kwargs = {"cache_control_injection_points": copy.deepcopy(self.SYSTEM_POINT)}
+        _, system = self._inject(
+            [{"role": "user", "content": "hi"}],
+            "sys",
+            kwargs,
+            model="anthropic/claude-sonnet-4-5",
+            custom_llm_provider="anthropic",
+        )
+        assert system == [{"type": "text", "text": "sys", "cache_control": {"type": "ephemeral"}}]
+        assert kwargs == {}
+
+    def test_v1_messages_older_openai_model_keeps_cache_control(self):
+        kwargs = {"cache_control_injection_points": copy.deepcopy(self.SYSTEM_POINT)}
+        _, system = self._inject([{"role": "user", "content": "hi"}], "sys", kwargs, model="openai/gpt-4.1")
+        assert system == [{"type": "text", "text": "sys", "cache_control": {"type": "ephemeral"}}]
+        assert kwargs == {}
+
+    def test_v1_messages_client_content_breakpoint_makes_configured_points_stand_down(self):
+        messages = [{"role": "user", "content": [{"type": "text", "text": "hi", "prompt_cache_breakpoint": self.EXPLICIT}]}]
+        kwargs = {"cache_control_injection_points": copy.deepcopy(self.SYSTEM_POINT)}
+        result, system = self._inject(messages, "sys", kwargs)
+        assert result == messages
+        assert system == "sys"
+        assert kwargs == {}
+
+    def test_v1_messages_client_system_breakpoint_makes_configured_points_stand_down(self):
+        system = [{"type": "text", "text": "sys", "prompt_cache_breakpoint": self.EXPLICIT}]
+        messages = [{"role": "user", "content": [{"type": "text", "text": "hi"}]}]
+        kwargs = {"cache_control_injection_points": [{"location": "message", "index": -1}]}
+        result, result_system = self._inject(messages, system, kwargs)
+        assert result == messages
+        assert result_system == system
+        assert kwargs == {}
+
+    def test_chat_system_string_wrapped_with_block_breakpoint(self):
+        params = {"cache_control_injection_points": copy.deepcopy(self.SYSTEM_POINT)}
+        messages = [{"role": "system", "content": "sys"}, {"role": "user", "content": "hi"}]
+        _, processed, returned = self._chat(messages, params)
+        assert processed[0] == {
+            "role": "system",
+            "content": [{"type": "text", "text": "sys", "prompt_cache_breakpoint": self.EXPLICIT}],
+        }
+        assert processed[1] == {"role": "user", "content": "hi"}
+        assert returned is params
+        assert returned == {"prompt_cache_options": self.EXPLICIT}
+
+    def test_chat_list_content_marks_last_block(self):
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "look"},
+                    {"type": "image_url", "image_url": {"url": "https://example.com/a.png"}},
+                ],
+            }
+        ]
+        params = {"cache_control_injection_points": [{"location": "message", "index": -1}]}
+        _, processed, _ = self._chat(messages, params)
+        assert processed[0]["content"] == [
+            {"type": "text", "text": "look"},
+            {
+                "type": "image_url",
+                "image_url": {"url": "https://example.com/a.png"},
+                "prompt_cache_breakpoint": self.EXPLICIT,
+            },
+        ]
+        assert params["prompt_cache_options"] == self.EXPLICIT
+
+    def test_chat_unprefixed_model_resolves_to_openai(self):
+        params = {"cache_control_injection_points": copy.deepcopy(self.SYSTEM_POINT)}
+        _, processed, _ = self._chat([{"role": "system", "content": "sys"}], params, model="gpt-5.6")
+        assert processed[0]["content"] == [{"type": "text", "text": "sys", "prompt_cache_breakpoint": self.EXPLICIT}]
+        assert params["prompt_cache_options"] == self.EXPLICIT
+
+    def test_chat_keeps_caller_prompt_cache_options(self):
+        params = {
+            "cache_control_injection_points": copy.deepcopy(self.SYSTEM_POINT),
+            "prompt_cache_options": {"mode": "implicit"},
+        }
+        self._chat([{"role": "system", "content": "sys"}], params)
+        assert params["prompt_cache_options"] == {"mode": "implicit"}
+
+    def test_chat_no_prompt_cache_options_when_nothing_injected(self):
+        params = {"cache_control_injection_points": copy.deepcopy(self.SYSTEM_POINT)}
+        messages = [{"role": "user", "content": "hi"}]
+        _, processed, _ = self._chat(messages, params)
+        assert processed == messages
+        assert params == {}
+
+    @pytest.mark.parametrize("model", ["openai/gpt-4.1", "anthropic/claude-sonnet-4-5"])
+    def test_chat_other_targets_keep_message_level_cache_control(self, model):
+        params = {"cache_control_injection_points": copy.deepcopy(self.SYSTEM_POINT)}
+        _, processed, _ = self._chat([{"role": "system", "content": "sys"}], params, model=model)
+        assert processed[0] == {"role": "system", "content": "sys", "cache_control": {"type": "ephemeral"}}
+        assert params == {}
+
+    def test_chat_client_breakpoint_makes_seeded_points_stand_down(self):
+        params = {"cache_control_injection_points": copy.deepcopy(self.SYSTEM_POINT)}
+        AnthropicCacheControlHook.maybe_seed_default_injection_points(
+            non_default_params=params,
+            messages=[
+                {"role": "system", "content": "sys"},
+                {"role": "user", "content": [{"type": "text", "text": "hi", "prompt_cache_breakpoint": self.EXPLICIT}]},
+            ],
+            model="openai/gpt-5.6",
+            custom_llm_provider="openai",
+        )
+        assert params == {}
+
+    def test_cap_counts_client_breakpoints_of_both_kinds(self):
+        messages = [
+            {"role": "user", "content": [{"type": "text", "text": "a", "prompt_cache_breakpoint": self.EXPLICIT}]},
+            {"role": "user", "content": [{"type": "text", "text": "b", "cache_control": {"type": "ephemeral"}}]},
+            {"role": "user", "content": [{"type": "text", "text": "c", "prompt_cache_breakpoint": self.EXPLICIT}]},
+            {"role": "user", "content": "d"},
+            {"role": "user", "content": "e"},
+        ]
+        result = AnthropicCacheControlHook._apply_message_injections(
+            points=[{"location": "message", "role": "user"}],
+            messages=copy.deepcopy(messages),
+            max_blocks=4,
+            openai_dialect=True,
+        )
+        assert result[:3] == messages[:3]
+        assert result[3]["content"] == [{"type": "text", "text": "d", "prompt_cache_breakpoint": self.EXPLICIT}]
+        assert result[4] == {"role": "user", "content": "e"}
+
+
+class TestOpenAIPromptCacheBreakpointPlacementRules:
+    """OpenAI dialect only marks blocks OpenAI (and the /v1/messages bridges) can carry (#37509)."""
+
+    EXPLICIT = {"mode": "explicit"}
+
+    def _chat(self, messages, points, model="openai/gpt-5.6"):
+        params = {"cache_control_injection_points": copy.deepcopy(points)}
+        _, out, params = AnthropicCacheControlHook().get_chat_completion_prompt(
+            model=model,
+            messages=copy.deepcopy(messages),
+            non_default_params=params,
+            prompt_id=None,
+            prompt_variables=None,
+            dynamic_callback_params={},
+        )
+        return out, params
+
+    def test_assistant_message_is_never_marked_on_chat_path(self):
+        messages = [{"role": "user", "content": "q"}, {"role": "assistant", "content": "a"}]
+        out, params = self._chat(messages, [{"location": "message", "role": "assistant"}])
+        assert out == messages
+        assert "prompt_cache_options" not in params
+
+    def test_tool_message_text_is_marked_on_chat_path(self):
+        messages = [
+            {"role": "user", "content": "weather?"},
+            {"role": "assistant", "content": None, "tool_calls": [{"id": "c1", "type": "function", "function": {"name": "w", "arguments": "{}"}}]},
+            {"role": "tool", "tool_call_id": "c1", "content": "sunny"},
+        ]
+        out, params = self._chat(messages, [{"location": "message", "index": -1}])
+        assert out[2]["content"] == [{"type": "text", "text": "sunny", "prompt_cache_breakpoint": self.EXPLICIT}]
+        assert params["prompt_cache_options"] == self.EXPLICIT
+
+    def test_tool_result_only_turn_is_skipped_on_v1_messages(self):
+        messages = [
+            {"role": "user", "content": [{"type": "text", "text": "q"}]},
+            {"role": "assistant", "content": [{"type": "tool_use", "id": "t1", "name": "w", "input": {}}]},
+            {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "t1", "content": "sunny"}]},
+        ]
+        kwargs = {"cache_control_injection_points": [{"location": "message", "index": -1}]}
+        out, system = AnthropicCacheControlHook.maybe_inject_cache_control(
+            copy.deepcopy(messages), None, kwargs, model="openai/gpt-5.6"
+        )
+        assert out == messages
+        assert system is None
+        assert "prompt_cache_options" not in kwargs
+
+    def test_assistant_turn_is_skipped_on_v1_messages(self):
+        messages = [
+            {"role": "user", "content": [{"type": "text", "text": "q"}]},
+            {"role": "assistant", "content": [{"type": "text", "text": "a"}]},
+        ]
+        kwargs = {"cache_control_injection_points": [{"location": "message", "role": "assistant"}]}
+        out, _ = AnthropicCacheControlHook.maybe_inject_cache_control(
+            copy.deepcopy(messages), None, kwargs, model="openai/gpt-5.6"
+        )
+        assert out == messages
+        assert "prompt_cache_options" not in kwargs
+
+    def test_text_after_tool_result_is_marked(self):
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "tool_result", "tool_use_id": "t1", "content": "sunny"},
+                    {"type": "text", "text": "thanks"},
+                ],
+            }
+        ]
+        kwargs = {"cache_control_injection_points": [{"location": "message", "index": -1}]}
+        out, _ = AnthropicCacheControlHook.maybe_inject_cache_control(messages, None, kwargs, model="openai/gpt-5.6")
+        assert out[0]["content"] == [
+            {"type": "tool_result", "tool_use_id": "t1", "content": "sunny"},
+            {"type": "text", "text": "thanks", "prompt_cache_breakpoint": self.EXPLICIT},
+        ]
+        assert kwargs["prompt_cache_options"] == self.EXPLICIT
+
+    def test_marker_walks_back_to_last_eligible_block(self):
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "read this"},
+                    {"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "doc"}},
+                ],
+            }
+        ]
+        kwargs = {"cache_control_injection_points": [{"location": "message", "index": -1}]}
+        out, _ = AnthropicCacheControlHook.maybe_inject_cache_control(messages, None, kwargs, model="openai/gpt-5.6")
+        assert out[0]["content"][0] == {"type": "text", "text": "read this", "prompt_cache_breakpoint": self.EXPLICIT}
+        assert "prompt_cache_breakpoint" not in out[0]["content"][1]
+
+    def test_skipped_block_does_not_consume_a_slot(self):
+        messages = [{"role": "user", "content": [{"type": "tool_result", "tool_use_id": "t0", "content": "r"}]}] + [
+            {"role": "user", "content": [{"type": "text", "text": f"m{i}"}]} for i in range(4)
+        ]
+        kwargs = {"cache_control_injection_points": [{"location": "message", "role": "user"}]}
+        out, _ = AnthropicCacheControlHook.maybe_inject_cache_control(messages, None, kwargs, model="openai/gpt-5.6")
+        assert "prompt_cache_breakpoint" not in out[0]["content"][0]
+        assert all(msg["content"][0]["prompt_cache_breakpoint"] == self.EXPLICIT for msg in out[1:])
+
+
+class TestChatPathProviderStamp:
+    """The chat path learns the caller's custom_llm_provider through the seeded points (#37509)."""
+
+    POINTS = [{"location": "message", "role": "system"}]
+    MESSAGES = [{"role": "system", "content": "sys"}, {"role": "user", "content": "hi"}]
+
+    def _seed_and_run(self, model, custom_llm_provider):
+        params = {"cache_control_injection_points": copy.deepcopy(self.POINTS)}
+        AnthropicCacheControlHook.maybe_seed_default_injection_points(
+            non_default_params=params,
+            messages=copy.deepcopy(self.MESSAGES),
+            model=model,
+            custom_llm_provider=custom_llm_provider,
+        )
+        _, out, params = AnthropicCacheControlHook().get_chat_completion_prompt(
+            model=model,
+            messages=copy.deepcopy(self.MESSAGES),
+            non_default_params=params,
+            prompt_id=None,
+            prompt_variables=None,
+            dynamic_callback_params={},
+        )
+        return out, params
+
+    def test_openai_compatible_provider_keeps_anthropic_style_markers(self):
+        out, params = self._seed_and_run("gpt-5.6", "hosted_vllm")
+        assert out[0] == {"role": "system", "content": "sys", "cache_control": {"type": "ephemeral"}}
+        assert "prompt_cache_options" not in params
+
+    def test_explicit_openai_provider_uses_openai_dialect(self):
+        out, params = self._seed_and_run("gpt-5.6", "openai")
+        assert out[0]["content"] == [{"type": "text", "text": "sys", "prompt_cache_breakpoint": {"mode": "explicit"}}]
+        assert params["prompt_cache_options"] == {"mode": "explicit"}
+
+    def test_bare_gpt_model_without_provider_resolves_to_openai(self):
+        out, params = self._seed_and_run("gpt-5.6", None)
+        assert out[0]["content"] == [{"type": "text", "text": "sys", "prompt_cache_breakpoint": {"mode": "explicit"}}]
+        assert params["prompt_cache_options"] == {"mode": "explicit"}
+
+    def test_points_keep_identity_for_models_below_gpt_5_6(self):
+        points = copy.deepcopy(self.POINTS)
+        params = {"cache_control_injection_points": points}
+        AnthropicCacheControlHook.maybe_seed_default_injection_points(
+            non_default_params=params,
+            messages=copy.deepcopy(self.MESSAGES),
+            model="anthropic/claude-sonnet-4-5",
+            custom_llm_provider="anthropic",
+        )
+        assert params["cache_control_injection_points"] is points
+
+    def test_provider_lookup_skipped_for_models_below_gpt_5_6(self):
+        from unittest.mock import patch
+
+        with patch.object(AnthropicCacheControlHook, "_resolve_provider") as resolve:
+            assert AnthropicCacheControlHook._targets_openai_prompt_cache_breakpoint("gpt-4.1", None) is False
+            assert AnthropicCacheControlHook._targets_openai_prompt_cache_breakpoint("my-custom-model", None) is False
+        resolve.assert_not_called()
+
+
+class TestClientBreakpointsCountedOnce:
+    def test_client_message_breakpoints_are_not_double_counted(self):
+        messages = [{"role": "user", "content": [{"type": "text", "text": "m0", "cache_control": {"type": "ephemeral"}}]}] + [
+            {"role": "user", "content": [{"type": "text", "text": f"m{i}"}]} for i in range(1, 4)
+        ]
+        out, system, _ = AnthropicCacheControlHook.apply_to_anthropic_messages_request(
+            messages=messages,
+            system="sys",
+            injection_points=[
+                {"location": "message", "role": "system"},
+                {"location": "message", "index": -1},
+                {"location": "message", "index": -2},
+                {"location": "message", "index": -3},
+            ],
+        )
+        marked = [msg["content"][0].get("cache_control") is not None for msg in out]
+        assert marked == [True, False, True, True]
+        assert system[0]["cache_control"] == {"type": "ephemeral"}
diff --git a/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_anthropic_experimental_pass_through_adapters_transformation.py b/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_anthropic_experimental_pass_through_adapters_transformation.py
index 1185893d428..abb976c3560 100644
--- a/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_anthropic_experimental_pass_through_adapters_transformation.py
+++ b/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_anthropic_experimental_pass_through_adapters_transformation.py
@@ -3741,3 +3741,59 @@ def test_tool_result_plain_text_unchanged_by_openai_transform():
     assert len(tool_messages) == 1
     assert tool_messages[0]["content"] == "42 files found"
     assert _image_urls_in_user_messages(result) == []
+
+
+def test_translate_anthropic_to_openai_carries_prompt_cache_breakpoint_on_system_and_user_blocks():
+    explicit = {"mode": "explicit"}
+    openai_request, _ = LiteLLMAnthropicMessagesAdapter().translate_anthropic_to_openai(
+        anthropic_message_request={
+            "model": "gpt-5.6",
+            "max_tokens": 64,
+            "system": [{"type": "text", "text": "sys", "prompt_cache_breakpoint": explicit}],
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "hi", "prompt_cache_breakpoint": explicit},
+                        {
+                            "type": "image",
+                            "source": {"type": "url", "url": "https://example.com/a.png"},
+                            "prompt_cache_breakpoint": explicit,
+                        },
+                    ],
+                }
+            ],
+        }
+    )
+    assert openai_request["messages"][0] == {
+        "role": "system",
+        "content": [{"type": "text", "text": "sys", "prompt_cache_breakpoint": explicit}],
+    }
+    user_content = openai_request["messages"][1]["content"]
+    assert user_content[0] == {"type": "text", "text": "hi", "prompt_cache_breakpoint": explicit}
+    assert user_content[1]["type"] == "image_url"
+    assert user_content[1]["prompt_cache_breakpoint"] == explicit
+
+
+def test_translate_anthropic_to_openai_without_prompt_cache_breakpoint_adds_nothing():
+    openai_request, _ = LiteLLMAnthropicMessagesAdapter().translate_anthropic_to_openai(
+        anthropic_message_request={
+            "model": "gpt-5.6",
+            "max_tokens": 64,
+            "system": [{"type": "text", "text": "sys"}],
+            "messages": [{"role": "user", "content": [{"type": "text", "text": "hi"}]}],
+        }
+    )
+    assert openai_request["messages"][0] == {"role": "system", "content": [{"type": "text", "text": "sys"}]}
+    assert openai_request["messages"][1]["content"] == [{"type": "text", "text": "hi"}]
+
+
+def test_translate_anthropic_messages_to_openai_carries_midturn_system_prompt_cache_breakpoint():
+    explicit = {"mode": "explicit"}
+    result = LiteLLMAnthropicMessagesAdapter().translate_anthropic_messages_to_openai(
+        messages=[{"role": "system", "content": [{"type": "text", "text": "fix", "prompt_cache_breakpoint": explicit}]}],
+        model="gpt-5.6",
+    )
+    assert result == [
+        {"role": "system", "content": [{"type": "text", "text": "fix", "prompt_cache_breakpoint": explicit}]}
+    ]
diff --git a/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_handler_output_config_passthrough.py b/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_handler_output_config_passthrough.py
index 615dc5cfebc..a944afc6152 100644
--- a/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_handler_output_config_passthrough.py
+++ b/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_handler_output_config_passthrough.py
@@ -230,3 +230,10 @@ class TestEmptyExtraKwargsPath:
         # dict-like result.
         completion_kwargs = result[0] if isinstance(result, tuple) else result
         assert isinstance(completion_kwargs, dict)
+
+
+class TestPromptCacheOptionsForwarded:
+    def test_prompt_cache_options_reaches_completion_kwargs(self):
+        result = _call_prepare(extra_kwargs={"prompt_cache_options": {"mode": "explicit"}}, model="gpt-5.6")
+        completion_kwargs = result[0] if isinstance(result, tuple) else result
+        assert completion_kwargs["prompt_cache_options"] == {"mode": "explicit"}
diff --git a/tests/test_litellm/llms/anthropic/experimental_pass_through/responses_adapters/test_responses_adapters_transformation.py b/tests/test_litellm/llms/anthropic/experimental_pass_through/responses_adapters/test_responses_adapters_transformation.py
index 876213eda3f..8228d41cf82 100644
--- a/tests/test_litellm/llms/anthropic/experimental_pass_through/responses_adapters/test_responses_adapters_transformation.py
+++ b/tests/test_litellm/llms/anthropic/experimental_pass_through/responses_adapters/test_responses_adapters_transformation.py
@@ -1413,3 +1413,155 @@ class TestToolResultImages:
         outputs = [item for item in items if item.get("type") == "function_call_output"]
         assert outputs[0]["output"] == "screenshot saved"
         assert self._input_images(items) == []
+
+
+def _contains_key(value, key) -> bool:
+    if isinstance(value, dict):
+        return key in value or any(_contains_key(v, key) for v in value.values())
+    if isinstance(value, list):
+        return any(_contains_key(v, key) for v in value)
+    return False
+
+
+class TestPromptCacheBreakpointToResponses:
+    """OpenAI `prompt_cache_breakpoint` markers ride through the /v1/messages -> Responses bridge (#37509)."""
+
+    EXPLICIT = {"mode": "explicit"}
+
+    def test_system_with_breakpoint_becomes_leading_developer_message(self):
+        request = _make_request(
+            model="openai/gpt-5.6",
+            system=[
+                {"type": "text", "text": "Be concise."},
+                {"type": "text", "text": "Be helpful.", "prompt_cache_breakpoint": self.EXPLICIT},
+            ],
+        )
+        kwargs = _ADAPTER.translate_request(request)
+        assert "instructions" not in kwargs
+        assert kwargs["input"] == [
+            {
+                "type": "message",
+                "role": "developer",
+                "content": [
+                    {"type": "input_text", "text": "Be concise."},
+                    {"type": "input_text", "text": "Be helpful.", "prompt_cache_breakpoint": self.EXPLICIT},
+                ],
+            },
+            {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "hello"}]},
+        ]
+
+    def test_system_without_breakpoint_still_becomes_instructions(self):
+        request = _make_request(system=[{"type": "text", "text": "Be concise."}, {"type": "text", "text": "Be helpful."}])
+        kwargs = _ADAPTER.translate_request(request)
+        assert kwargs["instructions"] == "Be concise.\nBe helpful."
+        assert kwargs["input"] == [
+            {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "hello"}]}
+        ]
+
+    def test_system_string_still_becomes_instructions(self):
+        kwargs = _ADAPTER.translate_request(_make_request(system="Be concise."))
+        assert kwargs["instructions"] == "Be concise."
+        assert kwargs["input"][0]["role"] == "user"
+
+    def test_system_with_breakpoint_skips_non_text_blocks(self):
+        request = _make_request(
+            system=[
+                {"type": "image", "source": {"type": "url", "url": "https://example.com/a.png"}},
+                {"type": "text", "text": "only", "prompt_cache_breakpoint": self.EXPLICIT},
+            ]
+        )
+        kwargs = _ADAPTER.translate_request(request)
+        assert kwargs["input"][0] == {
+            "type": "message",
+            "role": "developer",
+            "content": [{"type": "input_text", "text": "only", "prompt_cache_breakpoint": self.EXPLICIT}],
+        }
+
+    def test_user_text_and_image_blocks_carry_breakpoint(self):
+        items = _ADAPTER.translate_messages_to_responses_input(
+            [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "look", "prompt_cache_breakpoint": self.EXPLICIT},
+                        {
+                            "type": "image",
+                            "source": {"type": "url", "url": "https://example.com/a.png"},
+                            "prompt_cache_breakpoint": self.EXPLICIT,
+                        },
+                    ],
+                }
+            ]
+        )
+        assert items == [
+            {
+                "type": "message",
+                "role": "user",
+                "content": [
+                    {"type": "input_text", "text": "look", "prompt_cache_breakpoint": self.EXPLICIT},
+                    {
+                        "type": "input_image",
+                        "image_url": "https://example.com/a.png",
+                        "prompt_cache_breakpoint": self.EXPLICIT,
+                    },
+                ],
+            }
+        ]
+
+    def test_user_blocks_without_breakpoint_are_unchanged(self):
+        items = _ADAPTER.translate_messages_to_responses_input(
+            [{"role": "user", "content": [{"type": "text", "text": "look"}]}]
+        )
+        assert items == [{"type": "message", "role": "user", "content": [{"type": "input_text", "text": "look"}]}]
+
+    def test_midturn_system_block_carries_breakpoint(self):
+        items = _ADAPTER.translate_messages_to_responses_input(
+            [{"role": "system", "content": [{"type": "text", "text": "fix", "prompt_cache_breakpoint": self.EXPLICIT}]}]
+        )
+        assert items == [
+            {
+                "type": "message",
+                "role": "system",
+                "content": [{"type": "input_text", "text": "fix", "prompt_cache_breakpoint": self.EXPLICIT}],
+            }
+        ]
+
+    def test_assistant_and_tool_result_blocks_drop_breakpoint(self):
+        items = _ADAPTER.translate_messages_to_responses_input(
+            [
+                {"role": "user", "content": [{"type": "text", "text": "q"}]},
+                {
+                    "role": "assistant",
+                    "content": [
+                        {"type": "text", "text": "a", "prompt_cache_breakpoint": self.EXPLICIT},
+                        {"type": "tool_use", "id": "toolu_01", "name": "t", "input": {}},
+                    ],
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": "toolu_01",
+                            "content": "r",
+                            "prompt_cache_breakpoint": self.EXPLICIT,
+                        }
+                    ],
+                },
+            ]
+        )
+        assert len(items) == 4
+        assert not _contains_key(items, "prompt_cache_breakpoint")
+
+    def test_prompt_cache_options_forwarded_to_responses_kwargs(self):
+        from litellm.llms.anthropic.experimental_pass_through.responses_adapters.handler import (
+            _build_responses_kwargs,
+        )
+
+        kwargs = _build_responses_kwargs(
+            max_tokens=16,
+            messages=[{"role": "user", "content": "hi"}],
+            model="openai/gpt-5.6",
+            extra_kwargs={"prompt_cache_options": {"mode": "explicit"}},
+        )
+        assert kwargs["prompt_cache_options"] == {"mode": "explicit"}
diff --git a/tests/test_litellm/llms/openai/chat/test_openai_gpt_transformation.py b/tests/test_litellm/llms/openai/chat/test_openai_gpt_transformation.py
index 41c2e215c60..45f1bdbfa85 100644
--- a/tests/test_litellm/llms/openai/chat/test_openai_gpt_transformation.py
+++ b/tests/test_litellm/llms/openai/chat/test_openai_gpt_transformation.py
@@ -871,3 +871,48 @@ class TestToolMessageImageHoisting:
         result = request["messages"]
         assert [m.get("role") for m in result] == ["user", "assistant", "tool", "user"]
         assert result[3]["content"] == self.HOISTED_USER_CONTENT
+
+
+class TestOpenAIPromptCacheBreakpointChatPath:
+    """Chat-path shape for OpenAI explicit prompt caching (#37509)."""
+
+    EXPLICIT = {"mode": "explicit"}
+
+    def test_prompt_cache_options_travels_in_extra_body(self):
+        optional_params = litellm.get_optional_params(
+            model="gpt-5.6", custom_llm_provider="openai", prompt_cache_options=self.EXPLICIT
+        )
+        assert optional_params["extra_body"]["prompt_cache_options"] == self.EXPLICIT
+        assert "prompt_cache_options" not in optional_params
+
+    def test_prompt_cache_options_is_not_a_supported_chat_param(self):
+        assert "prompt_cache_options" not in OpenAIGPT5Config().get_supported_openai_params("gpt-5.6")
+        assert "prompt_cache_options" not in OpenAIGPTConfig().get_supported_openai_params("gpt-4.1")
+
+    def test_block_breakpoint_survives_transform_request(self):
+        request = OpenAIGPT5Config().transform_request(
+            model="gpt-5.6",
+            messages=[
+                {
+                    "role": "system",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "sys",
+                            "prompt_cache_breakpoint": self.EXPLICIT,
+                            "cache_control": {"type": "ephemeral"},
+                        }
+                    ],
+                },
+                {"role": "user", "content": [{"type": "text", "text": "hi", "prompt_cache_breakpoint": self.EXPLICIT}]},
+            ],
+            optional_params={"extra_body": {"prompt_cache_options": self.EXPLICIT}},
+            litellm_params={},
+            headers={},
+        )
+        assert request["messages"][0]["content"] == [
+            {"type": "text", "text": "sys", "prompt_cache_breakpoint": self.EXPLICIT}
+        ]
+        assert request["messages"][1]["content"] == [{"type": "text", "text": "hi", "prompt_cache_breakpoint": self.EXPLICIT}]
+        assert request["extra_body"] == {"prompt_cache_options": self.EXPLICIT}
+        assert "prompt_cache_options" not in request
diff --git a/tests/test_litellm/llms/openai/responses/test_openai_responses_transformation.py b/tests/test_litellm/llms/openai/responses/test_openai_responses_transformation.py
index 151c51f1ca0..13b96dc9943 100644
--- a/tests/test_litellm/llms/openai/responses/test_openai_responses_transformation.py
+++ b/tests/test_litellm/llms/openai/responses/test_openai_responses_transformation.py
@@ -1540,3 +1540,61 @@ class TestPhaseParameter:
         assert validated[0]["phase"] == "commentary"
         assert validated[1]["phase"] == "final_answer"
         assert "phase" not in validated[2]
+
+
+class TestPromptCacheOptionsOnResponsesPath:
+    """`prompt_cache_options` and block-level `prompt_cache_breakpoint` survive the Responses transformation (#37509)."""
+
+    OPTIONS = {"mode": "explicit", "ttl": "30m"}
+
+    def test_prompt_cache_options_survives_optional_param_filter(self):
+        from litellm.responses.utils import ResponsesAPIRequestUtils
+
+        result = ResponsesAPIRequestUtils.get_requested_response_api_optional_param(
+            {"prompt_cache_options": dict(self.OPTIONS), "temperature": 0.2, "not_a_responses_param": 1}
+        )
+        assert result["prompt_cache_options"] == self.OPTIONS
+        assert result["temperature"] == 0.2
+        assert "not_a_responses_param" not in result
+
+    def test_prompt_cache_options_reaches_transformed_request(self):
+        config = OpenAIResponsesAPIConfig()
+        mapped = config.map_openai_params(
+            response_api_optional_params={"prompt_cache_options": dict(self.OPTIONS)},
+            model="gpt-5.6",
+            drop_params=False,
+        )
+        result = config.transform_responses_api_request(
+            model="gpt-5.6",
+            input="hi",
+            response_api_optional_request_params=mapped,
+            litellm_params={},
+            headers={},
+        )
+        assert result["prompt_cache_options"] == self.OPTIONS
+
+    def test_prompt_cache_breakpoint_survives_cache_control_strip(self):
+        result = OpenAIResponsesAPIConfig().transform_responses_api_request(
+            model="gpt-5.6",
+            input=[
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "input_text",
+                            "text": "hi",
+                            "prompt_cache_breakpoint": {"mode": "explicit"},
+                            "cache_control": {"type": "ephemeral"},
+                        }
+                    ],
+                }
+            ],
+            response_api_optional_request_params={},
+            litellm_params={},
+            headers={},
+        )
+        assert result["input"][0]["content"][0] == {
+            "type": "input_text",
+            "text": "hi",
+            "prompt_cache_breakpoint": {"mode": "explicit"},
+        }

From 912206832c8a1ac5600d58ef5f2a560be372e948 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 04:29:01 -0700
Subject: [PATCH 14/35] fix(cli): pin PKCE discovery to the typed proxy and
 ignore foreign sibling records

The discovery document is accepted only when its issuer is the --base-url the user
typed and every endpoint and the resource share that origin (RFC 8414 section 3.3),
so a tampered or redirected document can no longer point the code, verifier, or
refresh token at another host. After a failed refresh the re-read token record is
used only when it continues the same credential (same proxy, token endpoint, and
resource) and has not expired, so a concurrent login against a different proxy can
never hand this one its key
---
 .../proxy/client/cli/commands/pkce_login.py   | 59 +++++++++++++-
 .../proxy/client/cli/test_pkce_login.py       | 80 +++++++++++++++++++
 2 files changed, 135 insertions(+), 4 deletions(-)

diff --git a/litellm/proxy/client/cli/commands/pkce_login.py b/litellm/proxy/client/cli/commands/pkce_login.py
index 6d6646a886c..2d8d5bf68bb 100644
--- a/litellm/proxy/client/cli/commands/pkce_login.py
+++ b/litellm/proxy/client/cli/commands/pkce_login.py
@@ -200,9 +200,49 @@ def discover_cli_auth(base_url: str, http: Http) -> CliAuthContract | PkceFailur
         return PkceFailure(f"{url} returned an unsupported discovery document: {exc}")
     if "S256" not in contract.code_challenge_methods_supported:
         return PkceFailure("the proxy does not support PKCE S256")
+    if _canonical_url(contract.issuer) != _canonical_url(base_url):
+        return PkceFailure(f"{url} is issued for {contract.issuer}, not {base_url}; pass that address as --base-url")
+    foreign: Final = _endpoints_outside(contract, _origin(base_url))
+    if foreign:
+        return PkceFailure(
+            f"{url} names endpoints outside {base_url} ({', '.join(foreign)}); refusing to send credentials there"
+        )
     return contract
 
 
+def _endpoints_outside(contract: CliAuthContract, origin: str | None) -> tuple[str, ...]:
+    endpoints: Final = (
+        contract.authorization_endpoint,
+        contract.token_endpoint,
+        contract.registration_endpoint,
+        contract.revocation_endpoint,
+        contract.resource,
+    )
+    return tuple(endpoint for endpoint in endpoints if origin is None or _origin(endpoint) != origin)
+
+
+def _origin(url: str) -> str | None:
+    """``scheme://host:port`` with the default port made explicit, so the same server spelled
+    two ways (``https://llm.example.com`` and ``https://LLM.example.com:443/``) compares equal
+    and two different servers never do."""
+    parsed: Final = urlparse(url)
+    try:
+        port: Final = parsed.port
+    except ValueError:
+        return None
+    if parsed.scheme not in ("http", "https") or not parsed.hostname:
+        return None
+    host: Final = f"[{parsed.hostname}]" if ":" in parsed.hostname else parsed.hostname
+    return f"{parsed.scheme}://{host}:{port or (443 if parsed.scheme == 'https' else 80)}"
+
+
+def _canonical_url(url: str) -> str | None:
+    """The origin plus the path with its trailing slash dropped: the RFC 8414 section 3.3
+    identity check, so a document can only ever be accepted for the proxy it was fetched from."""
+    origin: Final = _origin(url)
+    return None if origin is None else f"{origin}{urlparse(url).path.rstrip('/')}"
+
+
 class _ClientRegistration(TypedDict):
     client_name: ReadOnly[str]
     redirect_uris: ReadOnly[tuple[str, ...]]
@@ -423,7 +463,7 @@ def fresh_api_key(
     on file. The rotated pair is saved before the new key is returned, so a crash after
     this point never strands the CLI with a burned refresh token. A refresh that fails
     reads the record again, because a sibling ``lite`` process may have rotated the pair
-    first, in which case the key it saved is the live one. A record without
+    first, in which case the key it saved for this same proxy is the live one. A record without
     ``expires_at`` (the classic ``lite login`` credential) is returned as stored."""
     key: Final = token_data.get("key")
     if not isinstance(key, str) or not key:
@@ -439,14 +479,25 @@ def fresh_api_key(
         return still_valid
     refreshed: Final = refresh_credential(*refresh_inputs, http=http, now=now)
     if isinstance(refreshed, PkceFailure):
-        return _key_rotated_by_a_sibling(reload(), token_data.get("refresh_token")) or still_valid
+        return _key_rotated_by_a_sibling(reload(), token_data, now()) or still_valid
     base_url: Final = token_data.get("base_url")
     save(pkce_token_record(base_url if isinstance(base_url, str) else "", refreshed))
     return refreshed.access_token
 
 
-def _key_rotated_by_a_sibling(record: Mapping[str, object] | None, sent_refresh_token: object) -> str | None:
-    if record is None or record.get("refresh_token") == sent_refresh_token:
+def _key_rotated_by_a_sibling(
+    record: Mapping[str, object] | None, token_data: Mapping[str, object], now: float
+) -> str | None:
+    """The key a sibling process saved, but only when it continues this very credential:
+    same proxy, same token endpoint, same resource, and not yet expired. A concurrent
+    ``lite login`` against a different proxy replaces the same file, and its key must never
+    be sent to this one."""
+    if record is None or record.get("refresh_token") == token_data.get("refresh_token"):
+        return None
+    if any(record.get(field) != token_data.get(field) for field in ("base_url", "token_endpoint", "resource")):
+        return None
+    expires_at: Final = record.get("expires_at")
+    if not isinstance(expires_at, (int, float)) or now >= expires_at:
         return None
     key: Final = record.get("key")
     return key if isinstance(key, str) and key else None
diff --git a/tests/test_litellm/proxy/client/cli/test_pkce_login.py b/tests/test_litellm/proxy/client/cli/test_pkce_login.py
index 355d1c39d08..39f750835df 100644
--- a/tests/test_litellm/proxy/client/cli/test_pkce_login.py
+++ b/tests/test_litellm/proxy/client/cli/test_pkce_login.py
@@ -199,6 +199,15 @@ def test_discover_reads_the_contract_from_the_well_known_path():
         (_FakeResponse(200, text="<html>"), "unsupported discovery document"),
         (_FakeResponse(200, {**CONTRACT_DOC, "code_challenge_methods_supported": ["plain"]}), "PKCE S256"),
         (requests.ConnectionError("refused"), "could not reach"),
+        (_FakeResponse(200, {**CONTRACT_DOC, "issuer": "https://evil.example.com"}), "is issued for https://evil"),
+        (_FakeResponse(200, {**CONTRACT_DOC, "issuer": f"{BASE}/other"}), "is issued for"),
+        (_FakeResponse(200, {**CONTRACT_DOC, "issuer": "http://llm.example.com"}), "is issued for"),
+        (_FakeResponse(200, {**CONTRACT_DOC, "token_endpoint": "https://evil.example.com/token"}), "outside"),
+        (_FakeResponse(200, {**CONTRACT_DOC, "registration_endpoint": f"{BASE}:8443/register"}), "outside"),
+        (_FakeResponse(200, {**CONTRACT_DOC, "revocation_endpoint": "https://evil.example.com/revoke"}), "outside"),
+        (_FakeResponse(200, {**CONTRACT_DOC, "authorization_endpoint": "http://llm.example.com/authorize"}), "outside"),
+        (_FakeResponse(200, {**CONTRACT_DOC, "resource": "https://evil.example.com"}), "outside"),
+        (_FakeResponse(200, {**CONTRACT_DOC, "token_endpoint": "/token"}), "outside"),
     ],
 )
 def test_discover_failures_name_the_cause(response, expected):
@@ -207,6 +216,46 @@ def test_discover_failures_name_the_cause(response, expected):
     assert expected in result.reason
 
 
+def test_discover_refuses_endpoints_on_another_origin_and_names_each_of_them():
+    doc = {**CONTRACT_DOC, "token_endpoint": "https://evil.example.com/token", "resource": "https://evil.example.com"}
+    result = discover_cli_auth(BASE, _FakeHttp({("GET", DISCOVERY_URL): _FakeResponse(200, doc)}))
+    assert isinstance(result, PkceFailure)
+    assert "https://evil.example.com/token" in result.reason
+    assert "https://evil.example.com" in result.reason
+    assert "refusing to send credentials" in result.reason
+
+
+@pytest.mark.parametrize(
+    "typed_base_url",
+    ["https://LLM.example.com:443/", "https://llm.example.com", "HTTPS://llm.example.com/"],
+)
+def test_discover_accepts_the_same_proxy_however_the_user_spelled_it(typed_base_url):
+    discovery_url = f"{typed_base_url.rstrip('/')}/.well-known/litellm-cli-auth"
+    http = _FakeHttp({("GET", discovery_url): _FakeResponse(200, CONTRACT_DOC)})
+    assert discover_cli_auth(typed_base_url, http) == CONTRACT
+
+
+def test_discover_accepts_a_proxy_mounted_under_a_path_only_at_that_path():
+    mounted = f"{BASE}/litellm"
+    doc = {
+        **CONTRACT_DOC,
+        "issuer": mounted,
+        "authorization_endpoint": f"{mounted}/authorize",
+        "token_endpoint": f"{mounted}/token",
+        "registration_endpoint": f"{mounted}/register",
+        "revocation_endpoint": f"{mounted}/revoke",
+        "resource": mounted,
+    }
+    routes = {
+        ("GET", f"{mounted}/.well-known/litellm-cli-auth"): _FakeResponse(200, doc),
+        ("GET", DISCOVERY_URL): _FakeResponse(200, doc),
+    }
+    assert discover_cli_auth(f"{mounted}/", _FakeHttp(routes)) == CliAuthContract.model_validate(doc)
+    rejected = discover_cli_auth(BASE, _FakeHttp(routes))
+    assert isinstance(rejected, PkceFailure)
+    assert f"is issued for {mounted}" in rejected.reason
+
+
 def test_register_sends_a_public_loopback_client_and_returns_its_id():
     http = _FakeHttp({("POST", f"{BASE}/register"): _FakeResponse(201, {"client_id": "llm_dcrc_abc"})})
     assert register_client(CONTRACT, "http://127.0.0.1:5/callback", http) == "llm_dcrc_abc"
@@ -533,6 +582,37 @@ def test_fresh_api_key_uses_a_sibling_rotation_when_its_own_refresh_loses_the_ra
     assert saved == []
 
 
+@pytest.mark.parametrize(
+    "sibling_record",
+    [
+        {"base_url": "https://other.example.com", "token_endpoint": "https://other.example.com/token"},
+        {"base_url": "https://other.example.com", "resource": "https://other.example.com"},
+        {"base_url": "https://other.example.com"},
+        {"token_endpoint": "https://other.example.com/token"},
+        {"resource": "https://other.example.com"},
+        {"expires_at": 999_000.0},
+        {"expires_at": None},
+        {"key": ""},
+    ],
+    ids=[
+        "other-proxy",
+        "other-resource-line",
+        "other-base-url",
+        "other-token-endpoint",
+        "other-resource",
+        "expired",
+        "no-expiry",
+        "empty-key",
+    ],
+)
+def test_fresh_api_key_never_substitutes_a_sibling_record_for_another_proxy_or_a_dead_key(sibling_record):
+    rotated = {**STORED, "key": "sk-cli-sibling", "refresh_token": "llm_srefresh_sibling", "expires_at": 1_003_600.0}
+    foreign = {**rotated, **sibling_record}
+    http = _FakeHttp({("POST", f"{BASE}/token"): _FakeResponse(400, {"error": "invalid_grant"})})
+    assert _fresh(STORED, lambda _: None, http, reload=lambda: foreign, now=lambda: 1_000_001.0) is None
+    assert _fresh(STORED, lambda _: None, http, reload=lambda: foreign, now=lambda: 999_950.0) == "sk-cli-old"
+
+
 def test_fresh_api_key_without_refresh_inputs_expires_like_a_classic_key():
     http = _FakeHttp()
     no_refresh = {key: value for key, value in STORED.items() if key != "refresh_token"}

From 8e1c8c1c62b965e14a06492c34ec44f2f062e382 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 04:39:25 -0700
Subject: [PATCH 15/35] fix(anthropic): skip the derived prompt_cache_key for
 litellm_proxy deployments

---
 .../adapters/transformation.py                        |  3 +++
 ...perimental_pass_through_adapters_transformation.py | 11 +++++++++++
 .../adapters/test_handler_prompt_cache_key.py         |  6 ++++++
 3 files changed, 20 insertions(+)

diff --git a/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py b/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py
index 5c72fee25a0..974a3b4bb73 100644
--- a/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py
+++ b/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py
@@ -15,6 +15,7 @@ from litellm.llms.anthropic.experimental_pass_through.utils import (
 OPENAI_MAX_TOOL_NAME_LENGTH: Final = 64
 TOOL_NAME_HASH_LENGTH: Final = 8
 TOOL_NAME_PREFIX_LENGTH: Final = OPENAI_MAX_TOOL_NAME_LENGTH - TOOL_NAME_HASH_LENGTH - 1  # 55
+PROVIDERS_PROXYING_AN_UNKNOWN_BACKEND: Final = frozenset({"litellm_proxy"})
 
 
 def truncate_tool_name(name: str) -> str:
@@ -916,6 +917,8 @@ class LiteLLMAnthropicMessagesAdapter:
     def _supports_prompt_cache_key(model: str | None, custom_llm_provider: str | None) -> bool:
         if not model or not custom_llm_provider:
             return False
+        if custom_llm_provider in PROVIDERS_PROXYING_AN_UNKNOWN_BACKEND:
+            return False
         supported_params: Final = litellm.get_supported_openai_params(
             model=model, custom_llm_provider=custom_llm_provider
         )
diff --git a/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_anthropic_experimental_pass_through_adapters_transformation.py b/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_anthropic_experimental_pass_through_adapters_transformation.py
index dd1e8a93280..6edb3610bab 100644
--- a/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_anthropic_experimental_pass_through_adapters_transformation.py
+++ b/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_anthropic_experimental_pass_through_adapters_transformation.py
@@ -4,6 +4,8 @@ from typing import Any, cast
 
 import pytest
 
+import litellm
+
 sys.path.insert(0, os.path.abspath("../../../../.."))
 
 
@@ -688,6 +690,15 @@ def test_translate_anthropic_to_openai_skips_prompt_cache_key_when_provider_lack
     assert "prompt_cache_key" not in openai_request
 
 
+def test_translate_anthropic_to_openai_skips_prompt_cache_key_for_chained_litellm_proxy():
+    assert "prompt_cache_key" in litellm.get_supported_openai_params(
+        model="xai", custom_llm_provider="litellm_proxy"
+    )
+    openai_request = _translate_with_metadata("litellm_proxy/xai", {"user_id": "session-abc"}, "litellm_proxy")
+    assert openai_request["user"] == "session-abc"
+    assert "prompt_cache_key" not in openai_request
+
+
 def test_translate_anthropic_to_openai_skips_prompt_cache_key_without_provider():
     openai_request = _translate_with_metadata("openai/gpt-5.6-luna", {"user_id": "session-abc"}, None)
     assert openai_request["user"] == "session-abc"
diff --git a/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_handler_prompt_cache_key.py b/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_handler_prompt_cache_key.py
index ad6fc04217f..5b7f2a60f68 100644
--- a/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_handler_prompt_cache_key.py
+++ b/tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_handler_prompt_cache_key.py
@@ -54,6 +54,12 @@ def test_prepare_completion_kwargs_skips_prompt_cache_key_without_provider_suppo
     assert "prompt_cache_key" not in completion_kwargs
 
 
+def test_prepare_completion_kwargs_skips_prompt_cache_key_for_chained_litellm_proxy():
+    completion_kwargs = _prepare("litellm_proxy/xai", {"custom_llm_provider": "litellm_proxy"})
+    assert completion_kwargs["user"] == "session-abc"
+    assert "prompt_cache_key" not in completion_kwargs
+
+
 def test_prepare_completion_kwargs_keeps_prompt_cache_key_through_responses_reroute():
     completion_kwargs = _prepare(
         "openai/gpt-5.6-luna",

From fb123b33de18ad9eaa915feff04d6cac973a14e0 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 04:41:43 -0700
Subject: [PATCH 16/35] fix(cli): bind the sibling refresh fallback to the same
 user and team

---
 litellm/proxy/client/cli/commands/pkce_login.py       | 11 +++++++----
 .../test_litellm/proxy/client/cli/test_pkce_login.py  | 10 +++++++++-
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/litellm/proxy/client/cli/commands/pkce_login.py b/litellm/proxy/client/cli/commands/pkce_login.py
index 2d8d5bf68bb..d00f9a86bfe 100644
--- a/litellm/proxy/client/cli/commands/pkce_login.py
+++ b/litellm/proxy/client/cli/commands/pkce_login.py
@@ -485,16 +485,19 @@ def fresh_api_key(
     return refreshed.access_token
 
 
+_CREDENTIAL_IDENTITY_FIELDS: Final = ("base_url", "token_endpoint", "resource", "user_id", "team_id")
+
+
 def _key_rotated_by_a_sibling(
     record: Mapping[str, object] | None, token_data: Mapping[str, object], now: float
 ) -> str | None:
     """The key a sibling process saved, but only when it continues this very credential:
-    same proxy, same token endpoint, same resource, and not yet expired. A concurrent
-    ``lite login`` against a different proxy replaces the same file, and its key must never
-    be sent to this one."""
+    same proxy, same token endpoint, same resource, same user and team, and not yet expired.
+    A concurrent ``lite login`` against a different proxy, or as someone else on this one,
+    replaces the same file, and its key must never be sent as this credential."""
     if record is None or record.get("refresh_token") == token_data.get("refresh_token"):
         return None
-    if any(record.get(field) != token_data.get(field) for field in ("base_url", "token_endpoint", "resource")):
+    if any(record.get(field) != token_data.get(field) for field in _CREDENTIAL_IDENTITY_FIELDS):
         return None
     expires_at: Final = record.get("expires_at")
     if not isinstance(expires_at, (int, float)) or now >= expires_at:
diff --git a/tests/test_litellm/proxy/client/cli/test_pkce_login.py b/tests/test_litellm/proxy/client/cli/test_pkce_login.py
index 39f750835df..bbdcbb6635d 100644
--- a/tests/test_litellm/proxy/client/cli/test_pkce_login.py
+++ b/tests/test_litellm/proxy/client/cli/test_pkce_login.py
@@ -68,6 +68,8 @@ STORED = {
     "token_endpoint": f"{BASE}/token",
     "revocation_endpoint": f"{BASE}/revoke",
     "resource": BASE,
+    "user_id": "user-1",
+    "team_id": "team-a",
 }
 
 
@@ -590,6 +592,9 @@ def test_fresh_api_key_uses_a_sibling_rotation_when_its_own_refresh_loses_the_ra
         {"base_url": "https://other.example.com"},
         {"token_endpoint": "https://other.example.com/token"},
         {"resource": "https://other.example.com"},
+        {"user_id": "someone-else"},
+        {"team_id": "another-team"},
+        {"team_id": None},
         {"expires_at": 999_000.0},
         {"expires_at": None},
         {"key": ""},
@@ -600,12 +605,15 @@ def test_fresh_api_key_uses_a_sibling_rotation_when_its_own_refresh_loses_the_ra
         "other-base-url",
         "other-token-endpoint",
         "other-resource",
+        "other-user",
+        "other-team",
+        "no-team",
         "expired",
         "no-expiry",
         "empty-key",
     ],
 )
-def test_fresh_api_key_never_substitutes_a_sibling_record_for_another_proxy_or_a_dead_key(sibling_record):
+def test_fresh_api_key_never_substitutes_a_sibling_record_for_another_proxy_identity_or_a_dead_key(sibling_record):
     rotated = {**STORED, "key": "sk-cli-sibling", "refresh_token": "llm_srefresh_sibling", "expires_at": 1_003_600.0}
     foreign = {**rotated, **sibling_record}
     http = _FakeHttp({("POST", f"{BASE}/token"): _FakeResponse(400, {"error": "invalid_grant"})})

From 52c94327bd8f97cb1e216843ad923136ca92c5ef Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 05:17:00 -0700
Subject: [PATCH 17/35] fix(cli): renew a --pkce key wherever lite checks
 freshness and show its expiry in whoami

---
 litellm/litellm_core_utils/cli_token_utils.py |   6 +-
 litellm/proxy/client/README.md                |   7 +-
 litellm/proxy/client/cli/README.md            |   4 +-
 litellm/proxy/client/cli/commands/auth.py     |  17 ++-
 .../proxy/client/cli/commands/pkce_login.py   |   9 +-
 litellm/proxy/client/cli/commands/up.py       |  26 +++-
 .../proxy/client/cli/test_auth_commands.py    |  33 +++++
 .../proxy/client/cli/test_pkce_login.py       |  19 +++
 .../proxy/client/cli/test_up_commands.py      | 126 ++++++++++++++----
 9 files changed, 206 insertions(+), 41 deletions(-)

diff --git a/litellm/litellm_core_utils/cli_token_utils.py b/litellm/litellm_core_utils/cli_token_utils.py
index 0043bc31204..50694ae615f 100644
--- a/litellm/litellm_core_utils/cli_token_utils.py
+++ b/litellm/litellm_core_utils/cli_token_utils.py
@@ -12,6 +12,8 @@ from collections.abc import Mapping
 from pathlib import Path
 from typing import Final
 
+CLI_TOKEN_FRESHNESS_BUFFER_SECONDS: Final = 360
+
 
 def get_cli_token_file_path() -> str:
     """Get the path to the CLI token file"""
@@ -72,7 +74,9 @@ def get_litellm_gateway_api_key(
     return token_data["key"]
 
 
-def is_cli_token_fresh(token_data: Mapping[str, object], buffer_hours: float = 0.1) -> bool:
+def is_cli_token_fresh(
+    token_data: Mapping[str, object], buffer_hours: float = CLI_TOKEN_FRESHNESS_BUFFER_SECONDS / 3600
+) -> bool:
     """Check whether a cached CLI token (as stored in token.json) is still
     within its expiration window. Used by `lite auth print-token` to fail
     fast, without a network round trip, once the cached token is past
diff --git a/litellm/proxy/client/README.md b/litellm/proxy/client/README.md
index 6b28f43ac73..997c923de4d 100644
--- a/litellm/proxy/client/README.md
+++ b/litellm/proxy/client/README.md
@@ -339,9 +339,10 @@ sequenceDiagram
 The CLI provides these authentication commands:
 
 - **`lite login`** - Start SSO authentication flow
-- **`lite logout`** - Clear stored authentication token
+- **`lite login --pkce`** - Sign in through the system browser with OAuth authorization code + PKCE; the key renews itself with a refresh token
+- **`lite logout`** - Clear stored authentication token (and revoke a `--pkce` refresh token on the proxy)
 - **`lite whoami`** - Show current authentication status
-- **`lite auth print-token`** - Print the cached token (used as Claude Code's `apiKeyHelper`); fails once the token has expired
+- **`lite auth print-token`** - Print the cached token (used as Claude Code's `apiKeyHelper`); renews a `--pkce` key first and fails once a classic token has expired
 
 ### Authentication Flow Steps
 
@@ -377,7 +378,7 @@ Authentication tokens are stored in `~/.litellm/token.json` with restricted file
 }
 ```
 
-The stored credential is a short-lived, per-session agent token, not a managed virtual key. It is scoped to the user and team you logged in as and inherits their models and budgets; spend is tracked against the shared team and user budgets rather than a separate per-session cap, so multiple logins or several concurrent agents all draw down the same allowance. It is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); re-run `lite login` to refresh it and pick up your latest team and user settings. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it while fresh and fails once it expires -- there is no silent renewal. It is accepted on a default deployment without `EXPERIMENTAL_UI_LOGIN`, does not appear in the Keys UI, and cannot be rotated or revoked mid-session. For a long-lived, rotatable, Keys-UI-visible credential, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY`.
+The stored credential is a short-lived, per-session agent token, not a managed virtual key. It is scoped to the user and team you logged in as and inherits their models and budgets; spend is tracked against the shared team and user budgets rather than a separate per-session cap, so multiple logins or several concurrent agents all draw down the same allowance. It is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); re-run `lite login` to refresh it and pick up your latest team and user settings. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it while fresh and fails once it expires -- there is no silent renewal. It is accepted on a default deployment without `EXPERIMENTAL_UI_LOGIN`, does not appear in the Keys UI, and cannot be rotated or revoked mid-session. A credential from `lite login --pkce` is the exception: it carries a refresh token, so the CLI renews the key shortly before it expires and `lite logout` revokes the refresh token on the proxy (see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). For a long-lived, rotatable, Keys-UI-visible credential, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY`.
 
 ### Usage
 
diff --git a/litellm/proxy/client/cli/README.md b/litellm/proxy/client/cli/README.md
index 9fe52b7a27d..faa015a2f77 100644
--- a/litellm/proxy/client/cli/README.md
+++ b/litellm/proxy/client/cli/README.md
@@ -501,13 +501,13 @@ To pin the model, pass the agent's own model flag (for example `lite claude --mo
 
 The token minted by `lite login` is a short-lived, per-session agent credential, not a managed virtual key. It is scoped to the user and team you authenticated as, inherits that user's and team's models and budgets, and is enforced on the proxy exactly like a virtual key on the same team (guardrails, routing, logging, spend). Spend is tracked against the shared team and user budgets, so running several agents (or logging in more than once) does not hand each session its own separate budget; they all draw down the same team/user allowance. There is no separate per-session cap, so sustained agent use is not capped at a small chat-session limit.
 
-The credential is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); run `lite login` again to refresh it, which also re-reads your latest team and user settings. It does not appear in the Keys UI and cannot be rotated or revoked mid-session. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it while it's still fresh and fails once it expires -- there is no silent renewal, so a long-running session needs a fresh `lite login` once a day. `lite claude`, `lite codex`, and `lite opencode` work with it on a default deployment; `EXPERIMENTAL_UI_LOGIN` is not required. If you need a long-lived, rotatable key that shows up in the Keys UI, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY` instead.
+The credential is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); run `lite login` again to refresh it, which also re-reads your latest team and user settings. It does not appear in the Keys UI and cannot be rotated or revoked mid-session. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it while it's still fresh and fails once it expires -- there is no silent renewal, so a long-running session needs a fresh `lite login` once a day. `lite claude`, `lite codex`, and `lite opencode` work with it on a default deployment; `EXPERIMENTAL_UI_LOGIN` is not required. `lite login --pkce` is the exception to the daily re-login: it signs in through your system browser with OAuth authorization code and PKCE and stores a refresh token next to the key, so every `lite` command and `lite auth print-token` renew the key on their own shortly before it expires, `lite whoami` shows when the current key expires, and `lite logout` revokes the refresh token on the proxy (it needs a proxy that serves `/.well-known/litellm-cli-auth`; see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). If you need a long-lived, rotatable key that shows up in the Keys UI, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY` instead.
 
 ### Route Every Claude Code Session Through the Proxy
 
 `lite claude` wraps a single invocation, but `lite up` goes further: it patches `~/.claude/settings.json`, Claude Code's own config file, so that every Claude Code session started afterward -- from any terminal, launched normally with just `claude`, no wrapper needed -- routes through your LiteLLM proxy. It sets `env.ANTHROPIC_BASE_URL` to the proxy URL and `apiKeyHelper` to a `lite auth print-token` invocation, drops any stray static `ANTHROPIC_API_KEY` so the helper-issued token wins, and leaves every other setting in the file untouched. It backs up the original file before patching it.
 
-Two things need to already be true: you've run `lite login`, since the apiKeyHelper depends on that stored token, and the proxy is already reachable, since `lite up` does not start one for you.
+Two things need to already be true: you've run `lite login` (or `lite login --pkce`, whose key the helper renews on its own), since the apiKeyHelper depends on that stored token, and the proxy is already reachable, since `lite up` does not start one for you.
 
 ```bash
 lite login
diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py
index aee715686b7..bc7247055d8 100644
--- a/litellm/proxy/client/cli/commands/auth.py
+++ b/litellm/proxy/client/cli/commands/auth.py
@@ -837,16 +837,29 @@ def whoami():
     click.echo(f"User Email: {token_data.get('user_email', 'Unknown')}")
     click.echo(f"User ID: {token_data.get('user_id', 'Unknown')}")
     click.echo(f"User Role: {token_data.get('user_role', 'Unknown')}")
+    team_id: Final = token_data.get("team_id")
+    if team_id:
+        click.echo(f"Team ID: {team_id}")
 
-    # Check if token is still valid (basic timestamp check)
     timestamp: Final = token_data.get("timestamp", 0)
     age_hours: Final = (time.time() - timestamp) / 3600
     click.echo(f"Token age: {age_hours:.1f} hours")
 
-    if age_hours > CLI_JWT_EXPIRATION_HOURS:
+    expires_at: Final = token_data.get("expires_at")
+    if isinstance(expires_at, (int, float)):
+        click.echo(_key_expiry_line(expires_at, renews="refresh_token" in token_data))
+    elif age_hours > CLI_JWT_EXPIRATION_HOURS:
         click.echo(f"Warning: Token is more than {CLI_JWT_EXPIRATION_HOURS} hours old and may have expired.")
 
 
+def _key_expiry_line(expires_at: float, renews: bool) -> str:
+    remaining_hours: Final = (expires_at - time.time()) / 3600
+    status: Final = f"Key expires in: {remaining_hours:.1f} hours" if remaining_hours > 0 else "Key expired"
+    if renews:
+        return f"{status}, renewed on next use"
+    return status if remaining_hours > 0 else f"{status}. Run 'lite login' again"
+
+
 @click.group(name="auth")
 def auth_group():
     """Manage CLI authentication (apiKeyHelper support, etc.)"""
diff --git a/litellm/proxy/client/cli/commands/pkce_login.py b/litellm/proxy/client/cli/commands/pkce_login.py
index d00f9a86bfe..0e3b7c3271e 100644
--- a/litellm/proxy/client/cli/commands/pkce_login.py
+++ b/litellm/proxy/client/cli/commands/pkce_login.py
@@ -23,13 +23,14 @@ import requests
 from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, ValidationError
 from typing_extensions import ReadOnly, TypedDict
 
+from litellm.litellm_core_utils.cli_token_utils import CLI_TOKEN_FRESHNESS_BUFFER_SECONDS
+
 if TYPE_CHECKING:
     from .auth import CliTokenData
 
 CLI_AUTH_DISCOVERY_PATH: Final = "/.well-known/litellm-cli-auth"
 CALLBACK_PATH: Final = "/callback"
 LOGIN_TIMEOUT_SECONDS: Final = 300
-REFRESH_LEEWAY_SECONDS: Final = 60
 _HTTP_TIMEOUT_SECONDS: Final = 15
 _CLIENT_NAME: Final = "litellm-cli"
 
@@ -460,7 +461,9 @@ def fresh_api_key(
     now: Callable[[], float] = time.time,
 ) -> str | None:
     """The stored key, refreshed first when it is about to expire and a refresh token is
-    on file. The rotated pair is saved before the new key is returned, so a crash after
+    on file. The refresh fires at the same moment ``is_cli_token_fresh`` stops calling the
+    key fresh, so a command that checks freshness and then asks for the key never disagrees
+    with itself. The rotated pair is saved before the new key is returned, so a crash after
     this point never strands the CLI with a burned refresh token. A refresh that fails
     reads the record again, because a sibling ``lite`` process may have rotated the pair
     first, in which case the key it saved for this same proxy is the live one. A record without
@@ -471,7 +474,7 @@ def fresh_api_key(
     expires_at: Final = token_data.get("expires_at")
     if not isinstance(expires_at, (int, float)):
         return key
-    if now() < expires_at - REFRESH_LEEWAY_SECONDS:
+    if now() < expires_at - CLI_TOKEN_FRESHNESS_BUFFER_SECONDS:
         return key
     still_valid: Final = key if now() < expires_at else None
     refresh_inputs: Final = _refresh_inputs(token_data)
diff --git a/litellm/proxy/client/cli/commands/up.py b/litellm/proxy/client/cli/commands/up.py
index dd266b4afa1..35ca504c493 100644
--- a/litellm/proxy/client/cli/commands/up.py
+++ b/litellm/proxy/client/cli/commands/up.py
@@ -17,7 +17,7 @@ from pydantic import JsonValue, TypeAdapter, ValidationError
 from litellm.litellm_core_utils.cli_token_utils import is_cli_token_fresh
 
 from .agents import AgentRunError, resolve_api_key, verify_proxy_key
-from .auth import load_token, login
+from .auth import get_stored_api_key, load_token, login
 from .claude_settings import (
     BACKUP_PATH,
     CLAUDE_SETTINGS_PATH,
@@ -103,22 +103,34 @@ def restore_claude_settings(settings_path: Path | None = None, backup_path: Path
     return record
 
 
+def _usable_login(base_url: str) -> bool:
+    if get_stored_api_key(expected_base_url=base_url) is None:
+        return False
+    token_data: Final = load_token()
+    return token_data is not None and is_cli_token_fresh(token_data)
+
+
+def _stored_login_is_pkce() -> bool:
+    token_data: Final = load_token()
+    return token_data is not None and "refresh_token" in token_data
+
+
 def _ensure_fresh_login(ctx: click.Context) -> None:
     base_url: Final = ctx.obj["base_url"].rstrip("/")
-    token_data = load_token()
-    if token_data and token_data.get("base_url") == base_url and is_cli_token_fresh(token_data):
+    if _usable_login(base_url):
         return
 
+    pkce: Final = _stored_login_is_pkce()
+    login_command: Final = "lite login --pkce" if pkce else "lite login"
     if not sys.stdin.isatty():
         raise UpError(
-            "No fresh LiteLLM login found for this proxy. Run `lite login` first (apiKeyHelper "
+            f"No fresh LiteLLM login found for this proxy. Run `{login_command}` first (apiKeyHelper "
             "reads this token on every Claude Code request)."
         )
 
     click.echo("No fresh LiteLLM login found for this proxy; starting login...")
-    ctx.invoke(login)
-    token_data = load_token()
-    if not token_data or token_data.get("base_url") != base_url or not is_cli_token_fresh(token_data):
+    ctx.invoke(login, pkce=pkce)
+    if not _usable_login(base_url):
         raise UpError("Login did not produce a usable token; cannot start `lite up`.")
 
 
diff --git a/tests/test_litellm/proxy/client/cli/test_auth_commands.py b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
index dd86cba3f58..4e309bf1538 100644
--- a/tests/test_litellm/proxy/client/cli/test_auth_commands.py
+++ b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
@@ -626,6 +626,39 @@ class TestWhoamiCommand:
             assert "Authenticated" in result.output
             assert "Unknown" in result.output  # Should show "Unknown" for missing fields
 
+    def test_whoami_pkce_record_shows_the_team_and_when_the_key_renews(self):
+        token_data = {
+            "user_email": "unknown",
+            "user_id": "user-1",
+            "user_role": "cli",
+            "team_id": "team-alpha",
+            "timestamp": time.time() - 25 * 3600,
+            "expires_at": time.time() + 2 * 3600,
+            "refresh_token": "llm_srefresh_abc",
+        }
+
+        with patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=token_data):
+            result = self.runner.invoke(whoami)
+
+        assert result.exit_code == 0
+        assert "Team ID: team-alpha" in result.output
+        assert "Key expires in: 2.0 hours, renewed on next use" in result.output
+        assert "Warning" not in result.output
+
+    def test_whoami_expired_key_without_a_refresh_token_asks_for_a_new_login(self):
+        token_data = {
+            "user_id": "user-1",
+            "timestamp": time.time() - 3600,
+            "expires_at": time.time() - 60,
+        }
+
+        with patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=token_data):
+            result = self.runner.invoke(whoami)
+
+        assert result.exit_code == 0
+        assert "Team ID" not in result.output
+        assert "Key expired. Run 'lite login' again" in result.output
+
     def test_whoami_no_timestamp(self):
         """Test whoami with token missing timestamp"""
         token_data = {
diff --git a/tests/test_litellm/proxy/client/cli/test_pkce_login.py b/tests/test_litellm/proxy/client/cli/test_pkce_login.py
index bbdcbb6635d..db7d3c81d6c 100644
--- a/tests/test_litellm/proxy/client/cli/test_pkce_login.py
+++ b/tests/test_litellm/proxy/client/cli/test_pkce_login.py
@@ -5,6 +5,7 @@ import json
 import re
 import socket
 import threading
+import time
 import urllib.error
 import urllib.request
 from base64 import urlsafe_b64encode
@@ -13,6 +14,7 @@ from urllib.parse import parse_qs, urlparse
 import pytest
 import requests
 
+from litellm.litellm_core_utils.cli_token_utils import is_cli_token_fresh
 from litellm.proxy.client.cli.commands.pkce_login import (
     CallbackCode,
     CallbackDenied,
@@ -555,6 +557,23 @@ def test_fresh_api_key_refreshes_near_expiry_and_saves_before_returning():
     assert http.calls[0][2]["refresh_token"] == "llm_srefresh_old"
 
 
+@pytest.mark.parametrize(("seconds_left", "refreshes"), [(200, True), (600, False)])
+def test_fresh_api_key_refreshes_exactly_when_is_cli_token_fresh_stops_calling_the_key_fresh(
+    seconds_left, refreshes
+):
+    """`lite up` and `lite auth print-token` ask `is_cli_token_fresh` and then `fresh_api_key`; a key
+    the first calls stale that the second would not renew left `lite up` refusing a renewable login."""
+    record = {**STORED, "expires_at": time.time() + seconds_left}
+    http = _FakeHttp({("POST", f"{BASE}/token"): _FakeResponse(200, TOKEN_JSON)})
+    saved = []
+
+    key = _fresh(record, saved.append, http)
+
+    assert is_cli_token_fresh(record) is (not refreshes)
+    assert key == ("sk-cli-new" if refreshes else "sk-cli-old")
+    assert len(saved) == (1 if refreshes else 0)
+
+
 def test_fresh_api_key_never_hands_out_a_rotated_key_it_could_not_save():
     http = _FakeHttp({("POST", f"{BASE}/token"): _FakeResponse(200, TOKEN_JSON)})
 
diff --git a/tests/test_litellm/proxy/client/cli/test_up_commands.py b/tests/test_litellm/proxy/client/cli/test_up_commands.py
index 51de0dcf11d..6344e4ba154 100644
--- a/tests/test_litellm/proxy/client/cli/test_up_commands.py
+++ b/tests/test_litellm/proxy/client/cli/test_up_commands.py
@@ -2,6 +2,7 @@ import json
 import shutil
 import stat
 import sys
+import time
 from unittest.mock import patch
 
 import click
@@ -220,16 +221,62 @@ def _make_ctx(base_url):
     return click.Context(click.Command("test"), obj={"base_url": base_url})
 
 
+def _pkce_record(base_url, seconds_left):
+    return {
+        "key": "sk-pkce",
+        "base_url": base_url,
+        "expires_at": time.time() + seconds_left,
+        "refresh_token": "llm_srefresh_old",
+    }
+
+
+class _FakeTokenStore:
+    """Stands in for the token file: `get_stored_api_key` answers per proxy and may rotate the
+    record that `load_token` returns afterwards, exactly the side effect a refresh has on disk."""
+
+    def __init__(self, monkeypatch, record, keys_by_base_url, rotated_to=None):
+        self.record = record
+        self.keys_by_base_url = keys_by_base_url
+        self.rotated_to = rotated_to
+        self.key_requests = []
+        monkeypatch.setattr(up_module, "load_token", lambda: self.record)
+        monkeypatch.setattr(up_module, "get_stored_api_key", self.get_stored_api_key)
+
+    def get_stored_api_key(self, expected_base_url=None):
+        self.key_requests.append(expected_base_url)
+        key = self.keys_by_base_url.get(expected_base_url)
+        if key is not None and self.rotated_to is not None:
+            self.record = self.rotated_to
+        return key
+
+    def log_in(self, record, key):
+        self.record = record
+        self.keys_by_base_url = {record["base_url"]: key}
+
+
+def _capture_login(monkeypatch, on_login=lambda: None):
+    login_calls = []
+
+    @click.pass_context
+    def fake_login(ctx, pkce=False):
+        login_calls.append((ctx.obj["base_url"], pkce))
+        on_login()
+
+    monkeypatch.setattr(up_module, "login", fake_login)
+    return login_calls
+
+
 class TestEnsureFreshLogin:
     """A token that is fresh but was issued for a *different* proxy must not be trusted: without
     this check, a user logged into proxy A who runs `up --base-url proxy-b` would silently get an
     apiKeyHelper wired up around proxy A's real token, which print-token would then hand to proxy B."""
 
     def test_reuses_a_fresh_token_issued_for_the_same_proxy(self, monkeypatch):
-        monkeypatch.setattr(up_module, "load_token", lambda: {"key": "sk-a", "base_url": "http://proxy-a:4000"})
+        _FakeTokenStore(
+            monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {"http://proxy-a:4000": "sk-a"}
+        )
         monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
-        login_calls = []
-        monkeypatch.setattr(up_module, "login", lambda ctx: login_calls.append(ctx))
+        login_calls = _capture_login(monkeypatch)
 
         _ensure_fresh_login(_make_ctx("http://proxy-a:4000"))
 
@@ -237,34 +284,61 @@ class TestEnsureFreshLogin:
 
     def test_forces_a_fresh_login_when_the_cached_token_is_for_a_different_proxy(self, monkeypatch):
         monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True)
-        tokens = iter(
-            [
-                {"key": "sk-a", "base_url": "http://proxy-a:4000"},
-                {"key": "sk-b", "base_url": "http://proxy-b:4000"},
-            ]
-        )
-        monkeypatch.setattr(up_module, "load_token", lambda: next(tokens))
+        store = _FakeTokenStore(monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {})
         monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
-        login_calls = []
-
-        @click.pass_context
-        def fake_login(ctx):
-            login_calls.append(ctx.obj["base_url"])
-
-        monkeypatch.setattr(up_module, "login", fake_login)
+        login_calls = _capture_login(
+            monkeypatch, on_login=lambda: store.log_in({"key": "sk-b", "base_url": "http://proxy-b:4000"}, "sk-b")
+        )
 
         _ensure_fresh_login(_make_ctx("http://proxy-b:4000"))
 
-        assert login_calls == ["http://proxy-b:4000"]
+        assert login_calls == [("http://proxy-b:4000", False)]
+        assert store.key_requests == ["http://proxy-b:4000", "http://proxy-b:4000"]
 
     def test_fails_cleanly_non_interactively_when_only_a_different_proxys_token_is_cached(self, monkeypatch):
         monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: False)
-        monkeypatch.setattr(up_module, "load_token", lambda: {"key": "sk-a", "base_url": "http://proxy-a:4000"})
+        _FakeTokenStore(monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {})
         monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
 
-        with pytest.raises(UpError, match="lite login"):
+        with pytest.raises(UpError, match="Run `lite login` first"):
             _ensure_fresh_login(_make_ctx("http://proxy-b:4000"))
 
+    def test_trusts_a_pkce_credential_that_was_renewed_on_the_way_in(self, monkeypatch):
+        """A --pkce key inside its freshness buffer is renewed by `get_stored_api_key`, so `lite up`
+        must judge the rotated record rather than refuse the one it started with."""
+        monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: False)
+        store = _FakeTokenStore(
+            monkeypatch,
+            _pkce_record("http://proxy-a:4000", seconds_left=200),
+            {"http://proxy-a:4000": "sk-pkce-renewed"},
+            rotated_to=_pkce_record("http://proxy-a:4000", seconds_left=86_400),
+        )
+        login_calls = _capture_login(monkeypatch)
+
+        _ensure_fresh_login(_make_ctx("http://proxy-a:4000"))
+
+        assert login_calls == []
+        assert store.key_requests == ["http://proxy-a:4000"]
+
+    def test_logs_in_again_with_pkce_when_the_stale_credential_came_from_pkce(self, monkeypatch):
+        monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True)
+        store = _FakeTokenStore(monkeypatch, _pkce_record("http://proxy-a:4000", seconds_left=-10), {})
+        login_calls = _capture_login(
+            monkeypatch,
+            on_login=lambda: store.log_in(_pkce_record("http://proxy-a:4000", seconds_left=86_400), "sk-pkce-fresh"),
+        )
+
+        _ensure_fresh_login(_make_ctx("http://proxy-a:4000"))
+
+        assert login_calls == [("http://proxy-a:4000", True)]
+
+    def test_names_the_pkce_login_in_the_non_interactive_error_for_a_pkce_credential(self, monkeypatch):
+        monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: False)
+        _FakeTokenStore(monkeypatch, _pkce_record("http://proxy-a:4000", seconds_left=-10), {})
+
+        with pytest.raises(UpError, match="Run `lite login --pkce` first"):
+            _ensure_fresh_login(_make_ctx("http://proxy-a:4000"))
+
 
 class TestUpCommand:
     def setup_method(self):
@@ -277,6 +351,7 @@ class TestUpCommand:
 
         with (
             patch(f"{UP_MODULE}.load_token", return_value={"key": "sk-fresh", "base_url": "http://localhost:4000"}),
+            patch(f"{UP_MODULE}.get_stored_api_key", return_value="sk-fresh"),
             patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True),
             patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"),
             patch(f"{UP_MODULE}.verify_proxy_key"),
@@ -293,7 +368,10 @@ class TestUpCommand:
         _patch_paths(monkeypatch, tmp_path)
         monkeypatch.setattr(sys.stdin, "isatty", lambda: False)
 
-        with patch(f"{UP_MODULE}.load_token", return_value=None):
+        with (
+            patch(f"{UP_MODULE}.load_token", return_value=None),
+            patch(f"{UP_MODULE}.get_stored_api_key", return_value=None),
+        ):
             result = self.runner.invoke(up, obj={"base_url": "http://localhost:4000"})
 
         assert result.exit_code != 0
@@ -304,6 +382,7 @@ class TestUpCommand:
 
         with (
             patch(f"{UP_MODULE}.load_token", return_value={"key": "sk-fresh", "base_url": "http://localhost:4000"}),
+            patch(f"{UP_MODULE}.get_stored_api_key", return_value="sk-fresh"),
             patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True),
             patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"),
             patch(
@@ -330,6 +409,7 @@ class TestUpCommand:
 
         with (
             patch(f"{UP_MODULE}.load_token", return_value={"key": "sk-fresh", "base_url": "http://localhost:4000"}),
+            patch(f"{UP_MODULE}.get_stored_api_key", return_value="sk-fresh"),
             patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True),
             patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"),
             patch(f"{UP_MODULE}.verify_proxy_key"),
@@ -416,7 +496,7 @@ class TestUpCanInvokeTheRealLoginCommand:
         @click.pass_context
         def driver(ctx):
             ctx.obj = {"base_url": "http://127.0.0.1:9"}
-            ctx.invoke(real_login)
+            ctx.invoke(real_login, pkce=False)
 
         with patch(
             f"{AUTH_MODULE}._start_cli_sso_flow",
@@ -436,7 +516,7 @@ class TestUpCanInvokeTheRealLoginCommand:
         @click.pass_context
         def driver(ctx):
             ctx.obj = {"base_url": "http://127.0.0.1:9"}
-            ctx.invoke(real_login)
+            ctx.invoke(real_login, pkce=False)
 
         with (
             patch(f"{AUTH_MODULE}.CLAUDE_SETTINGS_PATH", settings_path),

From d9aaa959788efce33ad22c6887710028f0e2b27d Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 05:17:13 -0700
Subject: [PATCH 18/35] Gate OpenAI prompt cache breakpoints on the real target
 and carry them through /v1/responses

The cache control hook also runs on litellm.responses() input. On a
GPT-5.6 deployment it wrapped a string-content item into a chat-shaped
{"type": "text"} part, which the Responses API rejects, and it never
marked input_text, input_image or input_file parts, so no breakpoint and
no prompt_cache_options reached the provider. Add the Responses part
types to the eligible block set and translate chat-shaped text parts on
non-assistant items to input_text in
ResponsesAPIRequestUtils.merge_prompt_management_input, which both the
async and the sync prompt management sites go through.

The dialect also fired for any GPT-5.6 name that resolved to provider
openai, including deployments pointed at a custom api_base that does not
understand prompt_cache_breakpoint. Decide it once per request from the
provider, the model map and the resolved api_base (request, then
litellm.api_base, then OPENAI_BASE_URL / OPENAI_API_BASE): only
api.openai.com and *.api.openai.com hosts speak the dialect, a top-level
prompt_cache_options opts a custom target in, and litellm_proxy/ targets
never get it. maybe_seed_default_injection_points takes api_base and
stamps the finished decision on the points as _litellm_openai_dialect so
the sync completion() path, whose hook params do not carry api_base,
honors it; maybe_inject_cache_control takes api_base from the
/v1/messages handler.

Eligibility now comes from a supports_prompt_cache_breakpoint model map
flag on the OpenAI gpt-5.6 entries, exposed through
litellm.utils.supports_prompt_cache_breakpoint, with the GPT version rule
kept only for models the map does not know. The OpenAI dialect no longer
reserves a slot for tool_config points, which OpenAI has no cache block
for, and with_prompt_cache_breakpoint plus the chat bridge helper return
a new block instead of mutating their input.
---
 .../anthropic_cache_control_hook.py           | 113 ++++++--
 .../prompt_templates/common_utils.py          |  13 +-
 .../adapters/transformation.py                |  26 +-
 .../messages/handler.py                       |   4 +-
 litellm/main.py                               |   2 +
 ...odel_prices_and_context_window_backup.json |   4 +
 litellm/responses/utils.py                    |  13 +
 .../anthropic_cache_control_hook.py           |   4 +-
 litellm/types/utils.py                        |   1 +
 litellm/utils.py                              |  11 +
 model_prices_and_context_window.json          |   4 +
 model_prices_and_context_window.schema.json   |   3 +
 .../test_anthropic_cache_control_hook.py      | 270 +++++++++++++++++-
 .../test_responses_api_request_body.py        | 158 ++++++++++
 .../responses/test_responses_utils.py         |  62 ++++
 tests/test_litellm/test_main.py               |  46 +++
 tests/test_litellm/test_utils.py              |   1 +
 17 files changed, 692 insertions(+), 43 deletions(-)

diff --git a/litellm/integrations/anthropic_cache_control_hook.py b/litellm/integrations/anthropic_cache_control_hook.py
index 05e2a37a230..f65decc5463 100644
--- a/litellm/integrations/anthropic_cache_control_hook.py
+++ b/litellm/integrations/anthropic_cache_control_hook.py
@@ -10,9 +10,11 @@ Supported for both `v1/chat/completions` (via the prompt-management hook) and
 """
 
 import copy
+import os
 import re
 from collections.abc import Iterable, Mapping, Sequence
 from typing import TYPE_CHECKING, Any, Final, cast
+from urllib.parse import urlparse
 
 from litellm._logging import verbose_logger
 from litellm.integrations.custom_logger import CustomLogger
@@ -49,10 +51,18 @@ MAX_CACHE_CONTROL_BLOCKS: Final = 4
 CACHE_BREAKPOINT_KEYS: Final = ("cache_control", "prompt_cache_breakpoint")
 OPENAI_PROMPT_CACHE_BREAKPOINT_MIN_GPT_VERSION: Final = (5, 6)
 _GPT_VERSION_PATTERN: Final = re.compile(r"^gpt-(\d+)(?:\.(\d+))?")
-OPENAI_PROMPT_CACHE_BREAKPOINT_BLOCK_TYPES: Final = frozenset({"text", "image", "image_url", "file", "input_audio"})
+OPENAI_PROMPT_CACHE_BREAKPOINT_BLOCK_TYPES: Final = frozenset(
+    {"text", "image", "image_url", "file", "input_audio", "input_text", "input_image", "input_file"}
+)
+OPENAI_API_HOST: Final = "api.openai.com"
+OPENAI_API_BASE_ENV_VARS: Final = ("OPENAI_BASE_URL", "OPENAI_API_BASE")
 
 
 def supports_openai_prompt_cache_breakpoint(model: str) -> bool:
+    if _has_model_map_entry(model):
+        from litellm.utils import supports_prompt_cache_breakpoint
+
+        return supports_prompt_cache_breakpoint(model)
     version_match: Final = _GPT_VERSION_PATTERN.match(model.rsplit("/", 1)[-1].lower())
     if version_match is None:
         return False
@@ -60,6 +70,25 @@ def supports_openai_prompt_cache_breakpoint(model: str) -> bool:
     return version >= OPENAI_PROMPT_CACHE_BREAKPOINT_MIN_GPT_VERSION
 
 
+def _has_model_map_entry(model: str) -> bool:
+    import litellm
+
+    return model in litellm.model_cost or model.rsplit("/", 1)[-1] in litellm.model_cost
+
+
+def targets_openai_api(api_base: object) -> bool:
+    import litellm
+
+    resolved: Final = next(
+        (value for value in (api_base, litellm.api_base, *map(os.getenv, OPENAI_API_BASE_ENV_VARS)) if value),
+        None,
+    )
+    if not isinstance(resolved, str):
+        return True
+    host: Final = urlparse(resolved).hostname
+    return host is not None and (host == OPENAI_API_HOST or host.endswith(f".{OPENAI_API_HOST}"))
+
+
 def _carries_cache_breakpoint(block: object) -> bool:
     return isinstance(block, dict) and any(block.get(key) is not None for key in CACHE_BREAKPOINT_KEYS)
 
@@ -114,10 +143,19 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         # provider transform, where each tool_config point appends at most one
         # cachePoint to the tools. That block also counts toward Anthropic's
         # limit, so reserve a slot for it here to leave room.
-        reserved_blocks: Final = 1 if any(p.get("location") == "tool_config" for p in remaining_points) else 0
-
-        openai_dialect: Final = AnthropicCacheControlHook._targets_openai_prompt_cache_breakpoint(
-            model, injection_points[0].get("_litellm_provider")
+        stamped_dialect: Final = injection_points[0].get("_litellm_openai_dialect")
+        openai_dialect: Final = (
+            stamped_dialect
+            if isinstance(stamped_dialect, bool)
+            else AnthropicCacheControlHook._targets_openai_prompt_cache_breakpoint(
+                model,
+                non_default_params.get("custom_llm_provider"),
+                non_default_params.get("api_base"),
+                non_default_params.get("prompt_cache_options"),
+            )
+        )
+        reserved_blocks: Final = (
+            1 if not openai_dialect and any(p.get("location") == "tool_config" for p in remaining_points) else 0
         )
         breakpoints_before: Final = AnthropicCacheControlHook._count_request_cache_breakpoints(processed_messages)
         processed_messages = self._apply_message_injections(
@@ -141,10 +179,17 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         return model, processed_messages, non_default_params
 
     @staticmethod
-    def _targets_openai_prompt_cache_breakpoint(model: str | None, custom_llm_provider: str | None) -> bool:
+    def _targets_openai_prompt_cache_breakpoint(
+        model: str | None,
+        custom_llm_provider: str | None,
+        api_base: object = None,
+        prompt_cache_options: object = None,
+    ) -> bool:
         if model is None or not supports_openai_prompt_cache_breakpoint(model):
             return False
-        return (custom_llm_provider or AnthropicCacheControlHook._resolve_provider(model)) == "openai"
+        if (custom_llm_provider or AnthropicCacheControlHook._resolve_provider(model)) != "openai":
+            return False
+        return prompt_cache_options is not None or targets_openai_api(api_base)
 
     @staticmethod
     def _resolve_provider(model: str) -> str | None:
@@ -315,10 +360,18 @@ class AnthropicCacheControlHook(CustomPromptManagement):
             ]
             return marked
         if isinstance(message_content, list):
-            with_prompt_cache_breakpoint(
-                next((block for block in reversed(message_content) if _accepts_prompt_cache_breakpoint(block)), None),
-                PromptCacheBreakpoint(mode="explicit"),
+            target_index: Final = next(
+                (
+                    index
+                    for index in range(len(message_content) - 1, -1, -1)
+                    if _accepts_prompt_cache_breakpoint(message_content[index])
+                ),
+                None,
             )
+            if target_index is not None:
+                message_content[target_index] = with_prompt_cache_breakpoint(
+                    message_content[target_index], PromptCacheBreakpoint(mode="explicit")
+                )
         return message
 
     @staticmethod
@@ -363,7 +416,9 @@ class AnthropicCacheControlHook(CustomPromptManagement):
             else:
                 remaining_points.append(point)
 
-        reserved_blocks: Final = 1 if any(p.get("location") == "tool_config" for p in remaining_points) else 0
+        reserved_blocks: Final = (
+            1 if not openai_dialect and any(p.get("location") == "tool_config" for p in remaining_points) else 0
+        )
         max_blocks: Final = MAX_CACHE_CONTROL_BLOCKS - reserved_blocks
 
         message_blocks: Final = AnthropicCacheControlHook._count_request_cache_breakpoints(processed_messages)
@@ -432,18 +487,32 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         tools: list[object] | None,
         model: str,
         custom_llm_provider: str | None,
+        api_base: object,
+        prompt_cache_options: object,
     ) -> Sequence[Mapping[str, object]] | None:
         if AnthropicCacheControlHook._should_stand_down(points, messages, None, tools):
             return None
-        return AnthropicCacheControlHook._stamped_with_provider(points, model, custom_llm_provider)
+        return AnthropicCacheControlHook._stamped_with_dialect(
+            points, model, custom_llm_provider, api_base, prompt_cache_options
+        )
 
     @staticmethod
-    def _stamped_with_provider(
-        points: Sequence[CacheControlInjectionPoint], model: str, custom_llm_provider: str | None
+    def _stamped_with_dialect(
+        points: Sequence[CacheControlInjectionPoint],
+        model: str,
+        custom_llm_provider: str | None,
+        api_base: object,
+        prompt_cache_options: object,
     ) -> Sequence[Mapping[str, object]]:
-        if custom_llm_provider is None or not supports_openai_prompt_cache_breakpoint(model):
+        if not supports_openai_prompt_cache_breakpoint(model):
             return points
-        return AnthropicCacheControlHook._stamped(points, "_litellm_provider", custom_llm_provider)
+        return AnthropicCacheControlHook._stamped(
+            points,
+            "_litellm_openai_dialect",
+            AnthropicCacheControlHook._targets_openai_prompt_cache_breakpoint(
+                model, custom_llm_provider, api_base, prompt_cache_options
+            ),
+        )
 
     @staticmethod
     def _stamped(
@@ -563,6 +632,7 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         custom_llm_provider: str | None,
         tools: list | None = None,
         enable_prompt_caching: bool | None = None,
+        api_base: object = None,
     ) -> None:
         """For /chat/completions: resolve the injection points the request should carry.
 
@@ -578,7 +648,13 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         """
         if non_default_params.get("cache_control_injection_points"):
             judged: Final = AnthropicCacheControlHook._judged_configured_points(
-                non_default_params["cache_control_injection_points"], messages, tools, model, custom_llm_provider
+                non_default_params["cache_control_injection_points"],
+                messages,
+                tools,
+                model,
+                custom_llm_provider,
+                api_base,
+                non_default_params.get("prompt_cache_options"),
             )
             if judged is None:
                 non_default_params.pop("cache_control_injection_points")
@@ -604,6 +680,7 @@ class AnthropicCacheControlHook(CustomPromptManagement):
         model: str | None = None,
         custom_llm_provider: str | None = None,
         tools: list[dict] | None = None,
+        api_base: str | None = None,
     ) -> tuple[list[dict], str | list | None]:
         """Extract cache_control_injection_points from kwargs and apply if present.
 
@@ -642,7 +719,7 @@ class AnthropicCacheControlHook(CustomPromptManagement):
             return messages, system
 
         openai_dialect: Final = AnthropicCacheControlHook._targets_openai_prompt_cache_breakpoint(
-            model, custom_llm_provider
+            model, custom_llm_provider, api_base, kwargs.get("prompt_cache_options")
         )
         breakpoints_before: Final = AnthropicCacheControlHook._count_request_cache_breakpoints(messages, system)
         messages, system, remaining = AnthropicCacheControlHook.apply_to_anthropic_messages_request(
diff --git a/litellm/litellm_core_utils/prompt_templates/common_utils.py b/litellm/litellm_core_utils/prompt_templates/common_utils.py
index 5904a14e79f..2db5776047b 100644
--- a/litellm/litellm_core_utils/prompt_templates/common_utils.py
+++ b/litellm/litellm_core_utils/prompt_templates/common_utils.py
@@ -1325,17 +1325,14 @@ def check_is_function_call(logging_obj: "LoggingClass") -> bool:
     return False
 
 
-_MarkedT = TypeVar("_MarkedT")
-
-
-def _set_prompt_cache_breakpoint(target: object, marker: object) -> None:
-    if marker is not None and isinstance(target, dict):
-        target["prompt_cache_breakpoint"] = marker
+_MarkedT: Final = TypeVar("_MarkedT", bound=Mapping[str, object])
 
 
 def with_prompt_cache_breakpoint(target: _MarkedT, marker: object) -> _MarkedT:
-    _set_prompt_cache_breakpoint(target, marker)
-    return target
+    if marker is None:
+        return target
+    marked: Final = {**target, "prompt_cache_breakpoint": marker}  # mutable-ok: API message payload
+    return cast(_MarkedT, marked)  # cast-ok: same block shape as the input plus the marker key
 
 
 def filter_value_from_dict(dictionary: dict, key: str, depth: int = 0) -> Any:
diff --git a/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py b/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py
index 2ee50e2a55b..c6bfdb79002 100644
--- a/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py
+++ b/litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py
@@ -2,7 +2,7 @@ import copy
 import hashlib
 import json
 from collections.abc import AsyncIterator, Iterator, Mapping
-from typing import TYPE_CHECKING, Any, Final, Literal, cast
+from typing import TYPE_CHECKING, Any, Final, Literal, TypeVar, cast
 
 from litellm.llms.anthropic.experimental_pass_through.utils import (
     is_reasoning_auto_summary_enabled,
@@ -246,6 +246,9 @@ class AnthropicAdapter:
         return anthropic_wrapper.anthropic_sse_wrapper()
 
 
+_BlockT: Final = TypeVar("_BlockT", bound=Mapping[str, object])
+
+
 class LiteLLMAnthropicMessagesAdapter:
     def __init__(self):
         pass
@@ -310,9 +313,10 @@ class LiteLLMAnthropicMessagesAdapter:
                 cast(dict[str, object], target)["cache_control"] = cache_control
 
     @staticmethod
-    def _add_prompt_cache_breakpoint_if_present(source: object, target: object) -> None:
+    def _add_prompt_cache_breakpoint_if_present(source: object, target: _BlockT) -> _BlockT:
         if isinstance(source, dict) and "prompt_cache_breakpoint" in source:
-            with_prompt_cache_breakpoint(target, source["prompt_cache_breakpoint"])
+            return with_prompt_cache_breakpoint(target, source["prompt_cache_breakpoint"])
+        return target
 
     def translatable_anthropic_params(self) -> list[str]:
         """
@@ -374,8 +378,9 @@ class LiteLLMAnthropicMessagesAdapter:
                         if content.get("type") == "text":
                             text_obj = ChatCompletionTextObject(type="text", text=content.get("text", ""))
                             self._add_cache_control_if_applicable(content, text_obj, model)
-                            self._add_prompt_cache_breakpoint_if_present(content, text_obj)
-                            new_user_content_list.append(text_obj)
+                            new_user_content_list.append(
+                                self._add_prompt_cache_breakpoint_if_present(content, text_obj)
+                            )
                         elif content.get("type") == "image":
                             # Convert Anthropic image format to OpenAI format
                             source = content.get("source", {})
@@ -385,8 +390,9 @@ class LiteLLMAnthropicMessagesAdapter:
                                 image_url_obj = ChatCompletionImageUrlObject(url=openai_image_url)
                                 image_obj = ChatCompletionImageObject(type="image_url", image_url=image_url_obj)
                                 self._add_cache_control_if_applicable(content, image_obj, model)
-                                self._add_prompt_cache_breakpoint_if_present(content, image_obj)
-                                new_user_content_list.append(image_obj)
+                                new_user_content_list.append(
+                                    self._add_prompt_cache_breakpoint_if_present(content, image_obj)
+                                )
                         elif content.get("type") == "document":
                             # Convert Anthropic document format (PDF, etc.) to OpenAI format
                             source = content.get("source", {})
@@ -877,8 +883,7 @@ class LiteLLMAnthropicMessagesAdapter:
                 continue
             text_obj = ChatCompletionTextObject(type="text", text=text)
             self._add_cache_control_if_applicable(block, text_obj, model)
-            self._add_prompt_cache_breakpoint_if_present(block, text_obj)
-            text_parts.append(text_obj)
+            text_parts.append(self._add_prompt_cache_breakpoint_if_present(block, text_obj))
         return ChatCompletionSystemMessage(role="system", content=text_parts) if text_parts else None
 
     def _add_system_message_to_messages(
@@ -909,8 +914,7 @@ class LiteLLMAnthropicMessagesAdapter:
                         "text": block.get("text", ""),
                     }
                     self._add_cache_control_if_applicable(block, text_block, model_name)
-                    self._add_prompt_cache_breakpoint_if_present(block, text_block)
-                    openai_system_content.append(text_block)
+                    openai_system_content.append(self._add_prompt_cache_breakpoint_if_present(block, text_block))
             if openai_system_content:
                 new_messages.insert(
                     0,
diff --git a/litellm/llms/anthropic/experimental_pass_through/messages/handler.py b/litellm/llms/anthropic/experimental_pass_through/messages/handler.py
index c4b5cc628e2..26aef666172 100644
--- a/litellm/llms/anthropic/experimental_pass_through/messages/handler.py
+++ b/litellm/llms/anthropic/experimental_pass_through/messages/handler.py
@@ -230,7 +230,7 @@ async def anthropic_messages(
     )
 
     messages, system = AnthropicCacheControlHook.maybe_inject_cache_control(
-        messages, system, kwargs, model=model, custom_llm_provider=custom_llm_provider, tools=tools
+        messages, system, kwargs, model=model, custom_llm_provider=custom_llm_provider, tools=tools, api_base=api_base
     )
 
     original_stream: Final = stream or kwargs.get("_websearch_interception_converted_stream", False)
@@ -422,7 +422,7 @@ def anthropic_messages_handler(
     )
 
     messages, system = AnthropicCacheControlHook.maybe_inject_cache_control(
-        messages, system, kwargs, model=model, custom_llm_provider=custom_llm_provider, tools=tools
+        messages, system, kwargs, model=model, custom_llm_provider=custom_llm_provider, tools=tools, api_base=api_base
     )
 
     metadata = validate_anthropic_api_metadata(metadata)
diff --git a/litellm/main.py b/litellm/main.py
index f0b20eba9b6..87b32ab140c 100644
--- a/litellm/main.py
+++ b/litellm/main.py
@@ -507,6 +507,7 @@ async def acompletion(
         custom_llm_provider=cast(str | None, custom_llm_provider),  # cast-ok: read from untyped kwargs
         tools=tools,
         enable_prompt_caching=cast(bool | None, kwargs.get("enable_prompt_caching")),  # cast-ok: untyped kwargs
+        api_base=kwargs.get("api_base"),
     )
 
     if isinstance(litellm_logging_obj, LiteLLMLoggingObj) and (
@@ -5171,6 +5172,7 @@ def completion(
         custom_llm_provider=cast(str | None, kwargs.get("custom_llm_provider")),  # cast-ok: untyped kwargs
         tools=tools,
         enable_prompt_caching=cast(bool | None, kwargs.get("enable_prompt_caching")),  # cast-ok: untyped kwargs
+        api_base=kwargs.get("api_base"),
     )
 
     if isinstance(litellm_logging_obj, LiteLLMLoggingObj) and (
diff --git a/litellm/model_prices_and_context_window_backup.json b/litellm/model_prices_and_context_window_backup.json
index 3beb3ae4370..c92b4ccd18a 100644
--- a/litellm/model_prices_and_context_window_backup.json
+++ b/litellm/model_prices_and_context_window_backup.json
@@ -25368,6 +25368,7 @@
         "supports_none_reasoning_effort": true,
         "supports_parallel_function_calling": true,
         "supports_pdf_input": true,
+        "supports_prompt_cache_breakpoint": true,
         "supports_prompt_caching": true,
         "supports_reasoning": true,
         "supports_response_schema": true,
@@ -25430,6 +25431,7 @@
         "supports_none_reasoning_effort": true,
         "supports_parallel_function_calling": true,
         "supports_pdf_input": true,
+        "supports_prompt_cache_breakpoint": true,
         "supports_prompt_caching": true,
         "supports_reasoning": true,
         "supports_response_schema": true,
@@ -25492,6 +25494,7 @@
         "supports_none_reasoning_effort": true,
         "supports_parallel_function_calling": true,
         "supports_pdf_input": true,
+        "supports_prompt_cache_breakpoint": true,
         "supports_prompt_caching": true,
         "supports_reasoning": true,
         "supports_response_schema": true,
@@ -25554,6 +25557,7 @@
         "supports_none_reasoning_effort": true,
         "supports_parallel_function_calling": true,
         "supports_pdf_input": true,
+        "supports_prompt_cache_breakpoint": true,
         "supports_prompt_caching": true,
         "supports_reasoning": true,
         "supports_response_schema": true,
diff --git a/litellm/responses/utils.py b/litellm/responses/utils.py
index 4b5def790ed..504009802f2 100644
--- a/litellm/responses/utils.py
+++ b/litellm/responses/utils.py
@@ -40,12 +40,25 @@ def normalize_responses_api_stream_options(
 class ResponsesAPIRequestUtils:
     """Helper utils for constructing ResponseAPI requests"""
 
+    @staticmethod
+    def shape_prompt_managed_messages_for_responses(messages: Iterable[object]) -> None:
+        for message in messages:
+            if not isinstance(message, dict) or message.get("role") == "assistant":
+                continue
+            content: object = message.get("content")
+            if not isinstance(content, list):
+                continue
+            for part in content:
+                if isinstance(part, dict) and part.get("type") == "text":
+                    part["type"] = "input_text"
+
     @staticmethod
     def merge_prompt_management_input(
         original_input: str | ResponseInputParam,
         client_input: list[AllMessageValues],
         merged_input: list[AllMessageValues],
     ) -> list[object]:
+        ResponsesAPIRequestUtils.shape_prompt_managed_messages_for_responses(merged_input)
         if isinstance(original_input, str):
             return [*merged_input]
 
diff --git a/litellm/types/integrations/anthropic_cache_control_hook.py b/litellm/types/integrations/anthropic_cache_control_hook.py
index 3b3dcf5c86d..3ab0c02f28d 100644
--- a/litellm/types/integrations/anthropic_cache_control_hook.py
+++ b/litellm/types/integrations/anthropic_cache_control_hook.py
@@ -13,7 +13,7 @@ class CacheControlMessageInjectionPoint(TypedDict):
     index: int | str | None  # Optional: target by specific index
     control: ChatCompletionCachedContent | None
     _litellm_judged: NotRequired[bool]  # Internal: written back by litellm once the client cache_control judgment ran
-    _litellm_provider: NotRequired[ReadOnly[str]]
+    _litellm_openai_dialect: NotRequired[ReadOnly[bool]]
 
 
 class CacheControlToolConfigInjectionPoint(TypedDict):
@@ -22,7 +22,7 @@ class CacheControlToolConfigInjectionPoint(TypedDict):
     location: Literal["tool_config"]
     control: ChatCompletionCachedContent | None
     _litellm_judged: NotRequired[bool]  # Internal: written back by litellm once the client cache_control judgment ran
-    _litellm_provider: NotRequired[ReadOnly[str]]
+    _litellm_openai_dialect: NotRequired[ReadOnly[bool]]
 
 
 CacheControlInjectionPoint = CacheControlMessageInjectionPoint | CacheControlToolConfigInjectionPoint
diff --git a/litellm/types/utils.py b/litellm/types/utils.py
index 96b9343353d..41210d18495 100644
--- a/litellm/types/utils.py
+++ b/litellm/types/utils.py
@@ -141,6 +141,7 @@ class ProviderSpecificModelInfo(TypedDict, total=False):
     supports_tool_choice: bool | None
     supports_assistant_prefill: bool | None
     supports_prompt_caching: bool | None
+    supports_prompt_cache_breakpoint: ReadOnly[bool | None]
     supports_computer_use: bool | None
     supports_audio_input: bool | None
     supports_embedding_image_input: bool | None
diff --git a/litellm/utils.py b/litellm/utils.py
index d1b0cb882ac..867f7a93452 100644
--- a/litellm/utils.py
+++ b/litellm/utils.py
@@ -2560,6 +2560,14 @@ def supports_prompt_caching(model: str, custom_llm_provider: str | None = None)
     )
 
 
+def supports_prompt_cache_breakpoint(model: str, custom_llm_provider: str | None = None) -> bool:
+    return _supports_factory(
+        model=model,
+        custom_llm_provider=custom_llm_provider,
+        key="supports_prompt_cache_breakpoint",
+    )
+
+
 def supports_computer_use(model: str, custom_llm_provider: str | None = None) -> bool:
     """
     Check if the given model supports computer use and return a boolean value.
@@ -5473,6 +5481,7 @@ def _get_model_info_helper(
                 supports_tool_choice=None,
                 supports_assistant_prefill=None,
                 supports_prompt_caching=None,
+                supports_prompt_cache_breakpoint=None,
                 supports_computer_use=None,
                 supports_pdf_input=None,
             )
@@ -5712,6 +5721,7 @@ def _get_model_info_helper(
                 supports_tool_choice=_model_info.get("supports_tool_choice", None),
                 supports_assistant_prefill=_model_info.get("supports_assistant_prefill", None),
                 supports_prompt_caching=_model_info.get("supports_prompt_caching", None),
+                supports_prompt_cache_breakpoint=_model_info.get("supports_prompt_cache_breakpoint", None),
                 supports_audio_input=_model_info.get("supports_audio_input", None),
                 supports_audio_output=_model_info.get("supports_audio_output", None),
                 supports_pdf_input=_model_info.get("supports_pdf_input", None),
@@ -5846,6 +5856,7 @@ def get_model_info(
             supports_function_calling: Optional[bool]
             supports_tool_choice: Optional[bool]
             supports_prompt_caching: Optional[bool]
+            supports_prompt_cache_breakpoint: Optional[bool]
             supports_audio_input: Optional[bool]
             supports_audio_output: Optional[bool]
             supports_pdf_input: Optional[bool]
diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json
index 3beb3ae4370..c92b4ccd18a 100644
--- a/model_prices_and_context_window.json
+++ b/model_prices_and_context_window.json
@@ -25368,6 +25368,7 @@
         "supports_none_reasoning_effort": true,
         "supports_parallel_function_calling": true,
         "supports_pdf_input": true,
+        "supports_prompt_cache_breakpoint": true,
         "supports_prompt_caching": true,
         "supports_reasoning": true,
         "supports_response_schema": true,
@@ -25430,6 +25431,7 @@
         "supports_none_reasoning_effort": true,
         "supports_parallel_function_calling": true,
         "supports_pdf_input": true,
+        "supports_prompt_cache_breakpoint": true,
         "supports_prompt_caching": true,
         "supports_reasoning": true,
         "supports_response_schema": true,
@@ -25492,6 +25494,7 @@
         "supports_none_reasoning_effort": true,
         "supports_parallel_function_calling": true,
         "supports_pdf_input": true,
+        "supports_prompt_cache_breakpoint": true,
         "supports_prompt_caching": true,
         "supports_reasoning": true,
         "supports_response_schema": true,
@@ -25554,6 +25557,7 @@
         "supports_none_reasoning_effort": true,
         "supports_parallel_function_calling": true,
         "supports_pdf_input": true,
+        "supports_prompt_cache_breakpoint": true,
         "supports_prompt_caching": true,
         "supports_reasoning": true,
         "supports_response_schema": true,
diff --git a/model_prices_and_context_window.schema.json b/model_prices_and_context_window.schema.json
index 82854a3b717..0991650d307 100644
--- a/model_prices_and_context_window.schema.json
+++ b/model_prices_and_context_window.schema.json
@@ -664,6 +664,9 @@
         "supports_pdf_input": {
           "type": "boolean"
         },
+        "supports_prompt_cache_breakpoint": {
+          "type": "boolean"
+        },
         "supports_prompt_caching": {
           "type": "boolean"
         },
diff --git a/tests/test_litellm/integrations/test_anthropic_cache_control_hook.py b/tests/test_litellm/integrations/test_anthropic_cache_control_hook.py
index 04876b9bf12..4eb774af5bc 100644
--- a/tests/test_litellm/integrations/test_anthropic_cache_control_hook.py
+++ b/tests/test_litellm/integrations/test_anthropic_cache_control_hook.py
@@ -23,6 +23,13 @@ from litellm.types.llms.openai import AllMessageValues
 from litellm.types.utils import StandardCallbackDynamicParams
 
 
+@pytest.fixture(autouse=True)
+def _no_openai_api_base_override(monkeypatch):
+    monkeypatch.delenv("OPENAI_BASE_URL", raising=False)
+    monkeypatch.delenv("OPENAI_API_BASE", raising=False)
+    monkeypatch.setattr(litellm, "api_base", None)
+
+
 def _rendered_log_message(call):
     message = str(call.args[0])
     values = call.args[1:]
@@ -2395,19 +2402,28 @@ class TestOpenAIPromptCacheBreakpointPlacementRules:
 
 
 class TestChatPathProviderStamp:
-    """The chat path learns the caller's custom_llm_provider through the seeded points (#37509)."""
+    """The chat path learns the dialect decision (provider, api_base, opt-in) through the seeded points (#37509)."""
 
     POINTS = [{"location": "message", "role": "system"}]
     MESSAGES = [{"role": "system", "content": "sys"}, {"role": "user", "content": "hi"}]
+    ANTHROPIC_STYLE = {"role": "system", "content": "sys", "cache_control": {"type": "ephemeral"}}
+    OPENAI_STYLE = [{"type": "text", "text": "sys", "prompt_cache_breakpoint": {"mode": "explicit"}}]
+    CUSTOM_API_BASE = "http://127.0.0.1:9/v1"
 
-    def _seed_and_run(self, model, custom_llm_provider):
+    def _seed_and_run(self, model, custom_llm_provider, api_base=None, prompt_cache_options=None):
         params = {"cache_control_injection_points": copy.deepcopy(self.POINTS)}
+        if prompt_cache_options is not None:
+            params["prompt_cache_options"] = prompt_cache_options
         AnthropicCacheControlHook.maybe_seed_default_injection_points(
             non_default_params=params,
             messages=copy.deepcopy(self.MESSAGES),
             model=model,
             custom_llm_provider=custom_llm_provider,
+            api_base=api_base,
         )
+        return self._run(params, model)
+
+    def _run(self, params, model):
         _, out, params = AnthropicCacheControlHook().get_chat_completion_prompt(
             model=model,
             messages=copy.deepcopy(self.MESSAGES),
@@ -2452,6 +2468,84 @@ class TestChatPathProviderStamp:
             assert AnthropicCacheControlHook._targets_openai_prompt_cache_breakpoint("my-custom-model", None) is False
         resolve.assert_not_called()
 
+    def test_litellm_proxy_target_keeps_anthropic_style_markers(self):
+        out, params = self._seed_and_run("litellm_proxy/gpt-5.6", None)
+        assert out[0] == self.ANTHROPIC_STYLE
+        assert "prompt_cache_options" not in params
+
+    def test_custom_api_base_keeps_anthropic_style_markers(self):
+        out, params = self._seed_and_run("gpt-5.6", None, api_base=self.CUSTOM_API_BASE)
+        assert out[0] == self.ANTHROPIC_STYLE
+        assert "prompt_cache_options" not in params
+
+    def test_custom_api_base_opts_in_through_prompt_cache_options(self):
+        out, params = self._seed_and_run(
+            "gpt-5.6", None, api_base=self.CUSTOM_API_BASE, prompt_cache_options={"mode": "explicit"}
+        )
+        assert out[0]["content"] == self.OPENAI_STYLE
+        assert params["prompt_cache_options"] == {"mode": "explicit"}
+
+    def test_regional_openai_api_base_uses_openai_dialect(self):
+        out, params = self._seed_and_run("gpt-5.6", None, api_base="https://eu.api.openai.com/v1")
+        assert out[0]["content"] == self.OPENAI_STYLE
+        assert params["prompt_cache_options"] == {"mode": "explicit"}
+
+    @pytest.mark.parametrize("env_var", ["OPENAI_BASE_URL", "OPENAI_API_BASE"])
+    def test_env_api_base_override_keeps_anthropic_style_markers(self, monkeypatch, env_var):
+        monkeypatch.setenv(env_var, self.CUSTOM_API_BASE)
+        out, params = self._seed_and_run("gpt-5.6", None)
+        assert out[0] == self.ANTHROPIC_STYLE
+        assert "prompt_cache_options" not in params
+
+    def test_global_litellm_api_base_keeps_anthropic_style_markers(self, monkeypatch):
+        monkeypatch.setattr(litellm, "api_base", self.CUSTOM_API_BASE)
+        out, params = self._seed_and_run("gpt-5.6", None)
+        assert out[0] == self.ANTHROPIC_STYLE
+        assert "prompt_cache_options" not in params
+
+    def test_request_api_base_wins_over_env_override(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_BASE_URL", self.CUSTOM_API_BASE)
+        out, params = self._seed_and_run("gpt-5.6", None, api_base="https://api.openai.com/v1")
+        assert out[0]["content"] == self.OPENAI_STYLE
+        assert params["prompt_cache_options"] == {"mode": "explicit"}
+
+    @pytest.mark.parametrize(
+        "api_base,expected",
+        [(None, True), ("http://127.0.0.1:9/v1", False), ("https://eu.api.openai.com/v1", True)],
+    )
+    def test_seed_stamps_the_dialect_decision(self, api_base, expected):
+        params = {"cache_control_injection_points": copy.deepcopy(self.POINTS)}
+        AnthropicCacheControlHook.maybe_seed_default_injection_points(
+            non_default_params=params,
+            messages=copy.deepcopy(self.MESSAGES),
+            model="gpt-5.6",
+            custom_llm_provider=None,
+            api_base=api_base,
+        )
+        assert params["cache_control_injection_points"][0]["_litellm_openai_dialect"] is expected
+
+    def test_stamp_is_authoritative_over_request_params(self):
+        points = [{**self.POINTS[0], "_litellm_openai_dialect": False}]
+        out, params = self._run({"cache_control_injection_points": points, "custom_llm_provider": "openai"}, "gpt-5.6")
+        assert out[0] == self.ANTHROPIC_STYLE
+        assert "prompt_cache_options" not in params
+
+    def test_unstamped_points_read_api_base_from_request_params(self):
+        params = {"cache_control_injection_points": copy.deepcopy(self.POINTS), "api_base": self.CUSTOM_API_BASE}
+        out, params = self._run(params, "gpt-5.6")
+        assert out[0] == self.ANTHROPIC_STYLE
+        assert "prompt_cache_options" not in params
+
+    def test_unstamped_points_read_prompt_cache_options_from_request_params(self):
+        params = {
+            "cache_control_injection_points": copy.deepcopy(self.POINTS),
+            "api_base": self.CUSTOM_API_BASE,
+            "prompt_cache_options": {"mode": "explicit"},
+        }
+        out, params = self._run(params, "gpt-5.6")
+        assert out[0]["content"] == self.OPENAI_STYLE
+        assert params["prompt_cache_options"] == {"mode": "explicit"}
+
 
 class TestClientBreakpointsCountedOnce:
     def test_client_message_breakpoints_are_not_double_counted(self):
@@ -2471,3 +2565,175 @@ class TestClientBreakpointsCountedOnce:
         marked = [msg["content"][0].get("cache_control") is not None for msg in out]
         assert marked == [True, False, True, True]
         assert system[0]["cache_control"] == {"type": "ephemeral"}
+
+
+class TestResponsesInputPartsEligible:
+    """Responses API input parts can carry prompt_cache_breakpoint on GPT-5.6+ (#37509)."""
+
+    EXPLICIT = {"mode": "explicit"}
+
+    def _chat(self, messages, points, model="openai/gpt-5.6"):
+        params = {"cache_control_injection_points": copy.deepcopy(points)}
+        _, out, params = AnthropicCacheControlHook().get_chat_completion_prompt(
+            model=model,
+            messages=copy.deepcopy(messages),
+            non_default_params=params,
+            prompt_id=None,
+            prompt_variables=None,
+            dynamic_callback_params={},
+        )
+        return out, params
+
+    def test_marker_lands_on_last_input_text_part(self):
+        messages = [
+            {
+                "role": "user",
+                "content": [{"type": "input_text", "text": "first"}, {"type": "input_text", "text": "second"}],
+            }
+        ]
+        out, params = self._chat(messages, [{"location": "message", "index": -1}])
+        assert out[0]["content"][0] == {"type": "input_text", "text": "first"}
+        assert out[0]["content"][1] == {
+            "type": "input_text",
+            "text": "second",
+            "prompt_cache_breakpoint": self.EXPLICIT,
+        }
+        assert params["prompt_cache_options"] == self.EXPLICIT
+
+    @pytest.mark.parametrize(
+        "part",
+        [
+            {"type": "input_image", "image_url": "https://example.com/a.png"},
+            {"type": "input_file", "file_id": "file_1"},
+        ],
+    )
+    def test_input_image_and_input_file_parts_are_eligible(self, part):
+        out, params = self._chat([{"role": "user", "content": [part]}], [{"location": "message", "index": -1}])
+        assert out[0]["content"][0] == {**part, "prompt_cache_breakpoint": self.EXPLICIT}
+        assert params["prompt_cache_options"] == self.EXPLICIT
+
+
+class TestMessagesPathApiBaseGate:
+    """/v1/messages only speaks the OpenAI dialect when the request really targets api.openai.com (#37509)."""
+
+    EXPLICIT = {"mode": "explicit"}
+    USER_POINT = [{"location": "message", "role": "user"}]
+    MESSAGES = [{"role": "user", "content": [{"type": "text", "text": "hi"}]}]
+    CUSTOM_API_BASE = "http://127.0.0.1:9/v1"
+    CACHE_CONTROL_BLOCK = {"type": "text", "text": "hi", "cache_control": {"type": "ephemeral"}}
+    BREAKPOINT_BLOCK = {"type": "text", "text": "hi", "prompt_cache_breakpoint": {"mode": "explicit"}}
+
+    def _inject(self, model, api_base=None, prompt_cache_options=None, custom_llm_provider=None):
+        kwargs = {"cache_control_injection_points": copy.deepcopy(self.USER_POINT)}
+        if prompt_cache_options is not None:
+            kwargs["prompt_cache_options"] = prompt_cache_options
+        out, _ = AnthropicCacheControlHook.maybe_inject_cache_control(
+            copy.deepcopy(self.MESSAGES),
+            None,
+            kwargs,
+            model=model,
+            custom_llm_provider=custom_llm_provider,
+            api_base=api_base,
+        )
+        return out[0]["content"][0], kwargs
+
+    def test_litellm_proxy_target_keeps_cache_control(self):
+        block, kwargs = self._inject("gpt-5.6", api_base=self.CUSTOM_API_BASE, custom_llm_provider="litellm_proxy")
+        assert block == self.CACHE_CONTROL_BLOCK
+        assert "prompt_cache_options" not in kwargs
+
+    def test_custom_api_base_keeps_cache_control(self):
+        block, kwargs = self._inject("gpt-5.6", api_base=self.CUSTOM_API_BASE)
+        assert block == self.CACHE_CONTROL_BLOCK
+        assert "prompt_cache_options" not in kwargs
+
+    def test_custom_api_base_opts_in_through_prompt_cache_options(self):
+        block, kwargs = self._inject("gpt-5.6", api_base=self.CUSTOM_API_BASE, prompt_cache_options=self.EXPLICIT)
+        assert block == self.BREAKPOINT_BLOCK
+        assert kwargs["prompt_cache_options"] == self.EXPLICIT
+
+    def test_regional_openai_api_base_uses_openai_dialect(self):
+        block, kwargs = self._inject("gpt-5.6", api_base="https://eu.api.openai.com/v1")
+        assert block == self.BREAKPOINT_BLOCK
+        assert kwargs["prompt_cache_options"] == self.EXPLICIT
+
+    def test_default_api_base_uses_openai_dialect(self):
+        block, kwargs = self._inject("openai/gpt-5.6")
+        assert block == self.BREAKPOINT_BLOCK
+        assert kwargs["prompt_cache_options"] == self.EXPLICIT
+
+
+class TestToolConfigSlotInOpenAIDialect:
+    """OpenAI has no tool_config cache block, so the dialect does not hold a slot for one (#37509)."""
+
+    EXPLICIT = {"mode": "explicit"}
+    MESSAGES = [{"role": "user", "content": [{"type": "text", "text": f"m{i}"}]} for i in range(4)]
+    POINTS = [{"location": "message", "index": i} for i in range(4)] + [{"location": "tool_config"}]
+
+    def test_chat_path_marks_all_four_messages(self):
+        params = {"cache_control_injection_points": copy.deepcopy(self.POINTS)}
+        _, out, params = AnthropicCacheControlHook().get_chat_completion_prompt(
+            model="openai/gpt-5.6",
+            messages=copy.deepcopy(self.MESSAGES),
+            non_default_params=params,
+            prompt_id=None,
+            prompt_variables=None,
+            dynamic_callback_params={},
+        )
+        assert [msg["content"][0].get("prompt_cache_breakpoint") for msg in out] == [self.EXPLICIT] * 4
+        assert params["prompt_cache_options"] == self.EXPLICIT
+
+    def test_messages_path_marks_all_four_messages(self):
+        out, _, _ = AnthropicCacheControlHook.apply_to_anthropic_messages_request(
+            copy.deepcopy(self.MESSAGES), None, copy.deepcopy(self.POINTS), openai_dialect=True
+        )
+        assert [msg["content"][0].get("prompt_cache_breakpoint") for msg in out] == [self.EXPLICIT] * 4
+
+    def test_anthropic_dialect_still_reserves_the_tool_config_slot(self):
+        out, _, _ = AnthropicCacheControlHook.apply_to_anthropic_messages_request(
+            copy.deepcopy(self.MESSAGES), None, copy.deepcopy(self.POINTS)
+        )
+        assert sum(msg["content"][0].get("cache_control") is not None for msg in out) == 3
+
+
+class TestPromptCacheBreakpointCapability:
+    """Eligibility comes from the model map's supports_prompt_cache_breakpoint flag, with the GPT version
+    rule only for models the map does not know (#37509)."""
+
+    @pytest.fixture(autouse=True)
+    def _fresh_model_info_cache(self):
+        litellm.utils._cached_get_model_info_helper.cache_clear()
+        yield
+        litellm.utils._cached_get_model_info_helper.cache_clear()
+
+    def test_public_helper_reads_the_model_map(self):
+        from litellm.utils import supports_prompt_cache_breakpoint
+
+        assert supports_prompt_cache_breakpoint("gpt-5.6") is True
+        assert supports_prompt_cache_breakpoint("openai/gpt-5.6-sol") is True
+        assert supports_prompt_cache_breakpoint("gpt-5.6", custom_llm_provider="openai") is True
+        assert supports_prompt_cache_breakpoint("gpt-4.1") is False
+
+    @pytest.mark.parametrize("model", ["gpt-5.6", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"])
+    def test_model_map_flags_every_openai_gpt_5_6_entry(self, model):
+        assert litellm.model_cost[model]["litellm_provider"] == "openai"
+        assert litellm.model_cost[model]["supports_prompt_cache_breakpoint"] is True
+
+    def test_listed_model_uses_the_model_map_flag(self, monkeypatch):
+        flagged = {**litellm.model_cost["gpt-4.1"], "supports_prompt_cache_breakpoint": True}
+        monkeypatch.setitem(litellm.model_cost, "gpt-4.1", flagged)
+        assert supports_openai_prompt_cache_breakpoint("gpt-4.1") is True
+
+    def test_listed_gpt_5_6_without_the_flag_is_not_eligible(self, monkeypatch):
+        unflagged = {k: v for k, v in litellm.model_cost["gpt-5.6"].items() if k != "supports_prompt_cache_breakpoint"}
+        monkeypatch.setitem(litellm.model_cost, "gpt-5.6", unflagged)
+        assert supports_openai_prompt_cache_breakpoint("gpt-5.6") is False
+
+    def test_listed_gpt_model_without_the_flag_is_false(self):
+        assert "supports_prompt_cache_breakpoint" not in litellm.model_cost["gpt-4.1"]
+        assert supports_openai_prompt_cache_breakpoint("gpt-4.1") is False
+
+    @pytest.mark.parametrize("model,expected", [("gpt-5.6-2026-01-01", True), ("gpt-5.5-preview-unlisted", False)])
+    def test_unlisted_model_falls_back_to_the_version_rule(self, model, expected):
+        assert model not in litellm.model_cost
+        assert supports_openai_prompt_cache_breakpoint(model) is expected
diff --git a/tests/test_litellm/responses/test_responses_api_request_body.py b/tests/test_litellm/responses/test_responses_api_request_body.py
index ea5eb3afe9a..1402491a6b6 100644
--- a/tests/test_litellm/responses/test_responses_api_request_body.py
+++ b/tests/test_litellm/responses/test_responses_api_request_body.py
@@ -4,6 +4,7 @@ over the wire and surface provider errors correctly. Expected JSON bodies are st
 in expected_responses_api_request/.
 """
 
+import copy
 import json
 from pathlib import Path
 from unittest.mock import AsyncMock, patch
@@ -422,3 +423,160 @@ async def test_aresponses_websocket_strips_responses_routing_prefix_from_openai_
         mock_ws.assert_awaited_once()
         assert mock_ws.call_args.kwargs["model"] == "gpt-5.6"
         assert mock_ws.call_args.kwargs["custom_llm_provider"] == "openai"
+
+
+_INJECTION_POINT_INPUT = [{"role": "system", "content": "You are terse."}, {"role": "user", "content": "hi"}]
+_SYSTEM_INJECTION_POINT = [{"location": "message", "role": "system"}]
+
+
+def _sent_body(mock_post) -> dict:
+    kwargs = mock_post.call_args.kwargs
+    return kwargs["json"] if "json" in kwargs else json.loads(kwargs["data"])
+
+
+@pytest.mark.asyncio
+async def test_aresponses_injection_point_marks_input_text_on_gpt_5_6():
+    with patch(
+        "litellm.llms.custom_httpx.http_handler.AsyncHTTPHandler.post",
+        new_callable=AsyncMock,
+    ) as mock_post:
+        mock_post.return_value = MockResponse(_minimal_responses_api_payload("resp_pcb_async", "gpt-5.6"), 200)
+
+        await litellm.aresponses(
+            model="openai/gpt-5.6",
+            api_key="fake-api-key",
+            input=copy.deepcopy(_INJECTION_POINT_INPUT),
+            cache_control_injection_points=copy.deepcopy(_SYSTEM_INJECTION_POINT),
+        )
+
+        body = _sent_body(mock_post)
+        assert body["input"][0]["content"][0] == {
+            "type": "input_text",
+            "text": "You are terse.",
+            "prompt_cache_breakpoint": {"mode": "explicit"},
+        }
+        assert body["input"][1] == {"role": "user", "content": "hi"}
+        assert body["prompt_cache_options"] == {"mode": "explicit"}
+
+
+def test_responses_injection_point_marks_input_text_on_gpt_5_6():
+    with patch("litellm.llms.custom_httpx.http_handler.HTTPHandler.post") as mock_post:
+        mock_post.return_value = MockResponse(_minimal_responses_api_payload("resp_pcb_sync", "gpt-5.6"), 200)
+
+        litellm.responses(
+            model="openai/gpt-5.6",
+            api_key="fake-api-key",
+            input=copy.deepcopy(_INJECTION_POINT_INPUT),
+            cache_control_injection_points=copy.deepcopy(_SYSTEM_INJECTION_POINT),
+        )
+
+        body = _sent_body(mock_post)
+        assert body["input"][0]["content"][0] == {
+            "type": "input_text",
+            "text": "You are terse.",
+            "prompt_cache_breakpoint": {"mode": "explicit"},
+        }
+        assert body["input"][1] == {"role": "user", "content": "hi"}
+        assert body["prompt_cache_options"] == {"mode": "explicit"}
+
+
+@pytest.mark.asyncio
+async def test_aresponses_injection_point_sends_nothing_extra_below_gpt_5_6():
+    with patch(
+        "litellm.llms.custom_httpx.http_handler.AsyncHTTPHandler.post",
+        new_callable=AsyncMock,
+    ) as mock_post:
+        mock_post.return_value = MockResponse(_minimal_responses_api_payload("resp_pcb_old", "gpt-4.1"), 200)
+
+        await litellm.aresponses(
+            model="openai/gpt-4.1",
+            api_key="fake-api-key",
+            input=copy.deepcopy(_INJECTION_POINT_INPUT),
+            cache_control_injection_points=copy.deepcopy(_SYSTEM_INJECTION_POINT),
+        )
+
+        body = _sent_body(mock_post)
+        assert body["input"] == _INJECTION_POINT_INPUT
+        assert "prompt_cache_options" not in body
+        assert "cache_control" not in json.dumps(body)
+
+
+@pytest.fixture
+def _no_openai_api_base_override(monkeypatch):
+    monkeypatch.delenv("OPENAI_BASE_URL", raising=False)
+    monkeypatch.delenv("OPENAI_API_BASE", raising=False)
+    monkeypatch.setattr(litellm, "api_base", None)
+
+
+_CUSTOM_API_BASE = "http://127.0.0.1:9/v1"
+
+
+async def _aresponses_body_with_system_point(**request_kwargs) -> dict:
+    with patch(
+        "litellm.llms.custom_httpx.http_handler.AsyncHTTPHandler.post",
+        new_callable=AsyncMock,
+    ) as mock_post:
+        mock_post.return_value = MockResponse(_minimal_responses_api_payload("resp_pcb_gate", "gpt-5.6"), 200)
+        await litellm.aresponses(
+            api_key="fake-api-key",
+            input=copy.deepcopy(_INJECTION_POINT_INPUT),
+            cache_control_injection_points=copy.deepcopy(_SYSTEM_INJECTION_POINT),
+            **request_kwargs,
+        )
+        return _sent_body(mock_post)
+
+
+@pytest.mark.asyncio
+@pytest.mark.usefixtures("_no_openai_api_base_override")
+async def test_aresponses_litellm_proxy_target_sends_no_openai_markers():
+    body = await _aresponses_body_with_system_point(model="litellm_proxy/gpt-5.6", api_base=_CUSTOM_API_BASE)
+    assert body["input"] == _INJECTION_POINT_INPUT
+    assert "prompt_cache_options" not in body
+
+
+@pytest.mark.asyncio
+@pytest.mark.usefixtures("_no_openai_api_base_override")
+async def test_aresponses_custom_api_base_sends_no_openai_markers():
+    body = await _aresponses_body_with_system_point(model="gpt-5.6", api_base=_CUSTOM_API_BASE)
+    assert body["input"] == _INJECTION_POINT_INPUT
+    assert "prompt_cache_options" not in body
+
+
+@pytest.mark.asyncio
+@pytest.mark.usefixtures("_no_openai_api_base_override")
+async def test_aresponses_custom_api_base_opts_in_through_prompt_cache_options():
+    body = await _aresponses_body_with_system_point(
+        model="gpt-5.6", api_base=_CUSTOM_API_BASE, prompt_cache_options={"mode": "explicit"}
+    )
+    assert body["input"][0]["content"][0] == {
+        "type": "input_text",
+        "text": "You are terse.",
+        "prompt_cache_breakpoint": {"mode": "explicit"},
+    }
+    assert body["prompt_cache_options"] == {"mode": "explicit"}
+
+
+@pytest.mark.asyncio
+@pytest.mark.usefixtures("_no_openai_api_base_override")
+async def test_aresponses_regional_openai_api_base_marks_input_text():
+    body = await _aresponses_body_with_system_point(model="gpt-5.6", api_base="https://eu.api.openai.com/v1")
+    assert body["input"][0]["content"][0]["prompt_cache_breakpoint"] == {"mode": "explicit"}
+    assert body["prompt_cache_options"] == {"mode": "explicit"}
+
+
+@pytest.mark.usefixtures("_no_openai_api_base_override")
+def test_responses_custom_api_base_sends_no_openai_markers():
+    with patch("litellm.llms.custom_httpx.http_handler.HTTPHandler.post") as mock_post:
+        mock_post.return_value = MockResponse(_minimal_responses_api_payload("resp_pcb_gate_sync", "gpt-5.6"), 200)
+
+        litellm.responses(
+            model="gpt-5.6",
+            api_key="fake-api-key",
+            api_base=_CUSTOM_API_BASE,
+            input=copy.deepcopy(_INJECTION_POINT_INPUT),
+            cache_control_injection_points=copy.deepcopy(_SYSTEM_INJECTION_POINT),
+        )
+
+        body = _sent_body(mock_post)
+        assert body["input"] == _INJECTION_POINT_INPUT
+        assert "prompt_cache_options" not in body
diff --git a/tests/test_litellm/responses/test_responses_utils.py b/tests/test_litellm/responses/test_responses_utils.py
index 2b9e6d34828..35bf99db6dc 100644
--- a/tests/test_litellm/responses/test_responses_utils.py
+++ b/tests/test_litellm/responses/test_responses_utils.py
@@ -638,3 +638,65 @@ def test_responses_maps_reasoning_effort_from_litellm_params_to_reasoning():
             "effort": "high",
             "summary": "detailed",
         }
+
+
+class TestMergePromptManagementInputReshape:
+    """Chat-shaped text parts produced by prompt management hooks become input_text parts (#37509)."""
+
+    EXPLICIT = {"mode": "explicit"}
+
+    def _run_cache_hook(self, client_input, points, model="openai/gpt-5.6"):
+        from litellm.integrations.anthropic_cache_control_hook import AnthropicCacheControlHook
+
+        _, merged, _ = AnthropicCacheControlHook().get_chat_completion_prompt(
+            model=model,
+            messages=client_input,
+            non_default_params={"cache_control_injection_points": points},
+            prompt_id=None,
+            prompt_variables=None,
+            dynamic_callback_params={},
+        )
+        return merged
+
+    def test_string_system_item_becomes_input_text_with_marker(self):
+        original_input = [{"role": "system", "content": "You are terse."}, {"role": "user", "content": "hi"}]
+        merged = self._run_cache_hook(list(original_input), [{"location": "message", "role": "system"}])
+
+        result = ResponsesAPIRequestUtils.merge_prompt_management_input(
+            original_input=original_input, client_input=list(original_input), merged_input=merged
+        )
+
+        assert result[0]["content"] == [
+            {"type": "input_text", "text": "You are terse.", "prompt_cache_breakpoint": self.EXPLICIT}
+        ]
+        assert result[1] == {"role": "user", "content": "hi"}
+
+    def test_assistant_text_parts_are_left_alone(self):
+        merged = [
+            {"role": "assistant", "content": [{"type": "text", "text": "earlier answer"}]},
+            {"role": "user", "content": [{"type": "text", "text": "follow-up"}]},
+        ]
+
+        result = ResponsesAPIRequestUtils.merge_prompt_management_input(
+            original_input="ignored", client_input=[], merged_input=merged
+        )
+
+        assert result[0]["content"] == [{"type": "text", "text": "earlier answer"}]
+        assert result[1]["content"] == [{"type": "input_text", "text": "follow-up"}]
+
+    def test_parts_already_in_responses_shape_are_unchanged(self):
+        merged = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "input_text", "text": "a", "prompt_cache_breakpoint": self.EXPLICIT},
+                    {"type": "input_image", "image_url": "https://example.com/a.png"},
+                ],
+            }
+        ]
+
+        result = ResponsesAPIRequestUtils.merge_prompt_management_input(
+            original_input="ignored", client_input=[], merged_input=merged
+        )
+
+        assert result == merged
diff --git a/tests/test_litellm/test_main.py b/tests/test_litellm/test_main.py
index 68b8d1c62b5..786adf2d78b 100644
--- a/tests/test_litellm/test_main.py
+++ b/tests/test_litellm/test_main.py
@@ -2672,3 +2672,49 @@ def test_openai_model_without_a_provider_still_routes_to_openai():
         )
 
     mock_create.assert_called()
+
+
+def _openai_chat_create_kwargs(client, **completion_kwargs):
+    with patch.object(client.chat.completions.with_raw_response, "create") as mock_client:
+        with contextlib.suppress(Exception):
+            litellm.completion(
+                messages=[{"role": "system", "content": "sys"}, {"role": "user", "content": "hi"}],
+                cache_control_injection_points=[{"location": "message", "role": "system"}],
+                client=client,
+                **completion_kwargs,
+            )
+
+        mock_client.assert_called_once()
+        return mock_client.call_args.kwargs
+
+
+@pytest.fixture
+def _no_openai_api_base_override(monkeypatch):
+    monkeypatch.delenv("OPENAI_BASE_URL", raising=False)
+    monkeypatch.delenv("OPENAI_API_BASE", raising=False)
+    monkeypatch.setattr(litellm, "api_base", None)
+
+
+@pytest.mark.usefixtures("_no_openai_api_base_override")
+def test_completion_custom_api_base_sends_no_prompt_cache_breakpoint_for_gpt_5_6():
+    from openai import OpenAI
+
+    client = OpenAI(api_key="fake-api-key", base_url="http://127.0.0.1:9/v1")
+    request_body = _openai_chat_create_kwargs(client, model="gpt-5.6", api_base="http://127.0.0.1:9/v1")
+
+    assert request_body["messages"][0] == {"role": "system", "content": "sys", "cache_control": {"type": "ephemeral"}}
+    assert "prompt_cache_breakpoint" not in json.dumps(request_body["messages"])
+    assert "prompt_cache_options" not in json.dumps(request_body)
+
+
+@pytest.mark.usefixtures("_no_openai_api_base_override")
+def test_completion_default_api_base_sends_prompt_cache_breakpoint_for_gpt_5_6():
+    from openai import OpenAI
+
+    client = OpenAI(api_key="fake-api-key")
+    request_body = _openai_chat_create_kwargs(client, model="gpt-5.6")
+
+    assert request_body["messages"][0]["content"] == [
+        {"type": "text", "text": "sys", "prompt_cache_breakpoint": {"mode": "explicit"}}
+    ]
+    assert request_body["extra_body"]["prompt_cache_options"] == {"mode": "explicit"}
diff --git a/tests/test_litellm/test_utils.py b/tests/test_litellm/test_utils.py
index 60453931595..cb58038e081 100644
--- a/tests/test_litellm/test_utils.py
+++ b/tests/test_litellm/test_utils.py
@@ -921,6 +921,7 @@ def test_aaamodel_prices_and_context_window_json_is_valid():
                 "supports_parallel_tool_use_config": {"type": "boolean"},
                 "supports_pdf_input": {"type": "boolean"},
                 "prompt_cache_min_tokens": {"type": "number"},
+                "supports_prompt_cache_breakpoint": {"type": "boolean"},
                 "supports_prompt_caching": {"type": "boolean"},
                 "supports_response_schema": {"type": "boolean"},
                 "supports_system_messages": {"type": "boolean"},

From c011b4b56ffdadd2600549e387a5109eb79263da Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 05:22:26 -0700
Subject: [PATCH 19/35] fix(cli): tell whoami's expired PKCE key to sign in
 again instead of promising a renewal

---
 litellm/proxy/client/cli/commands/auth.py        |  8 ++++----
 .../proxy/client/cli/test_auth_commands.py       | 16 ++++++++++++++++
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py
index bc7247055d8..b8266b7d6eb 100644
--- a/litellm/proxy/client/cli/commands/auth.py
+++ b/litellm/proxy/client/cli/commands/auth.py
@@ -854,10 +854,10 @@ def whoami():
 
 def _key_expiry_line(expires_at: float, renews: bool) -> str:
     remaining_hours: Final = (expires_at - time.time()) / 3600
-    status: Final = f"Key expires in: {remaining_hours:.1f} hours" if remaining_hours > 0 else "Key expired"
-    if renews:
-        return f"{status}, renewed on next use"
-    return status if remaining_hours > 0 else f"{status}. Run 'lite login' again"
+    if remaining_hours <= 0:
+        return f"Key expired. Run '{'lite login --pkce' if renews else 'lite login'}' again"
+    status: Final = f"Key expires in: {remaining_hours:.1f} hours"
+    return f"{status}, renewed on next use" if renews else status
 
 
 @click.group(name="auth")
diff --git a/tests/test_litellm/proxy/client/cli/test_auth_commands.py b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
index 4e309bf1538..27568534bb6 100644
--- a/tests/test_litellm/proxy/client/cli/test_auth_commands.py
+++ b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
@@ -659,6 +659,22 @@ class TestWhoamiCommand:
         assert "Team ID" not in result.output
         assert "Key expired. Run 'lite login' again" in result.output
 
+    def test_whoami_expired_pkce_record_that_could_not_be_renewed_asks_for_a_new_pkce_login(self):
+        token_data = {
+            "user_id": "user-1",
+            "team_id": "team-alpha",
+            "timestamp": time.time() - 3600,
+            "expires_at": time.time() - 60,
+            "refresh_token": "llm_srefresh_spent",
+        }
+
+        with patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=token_data):
+            result = self.runner.invoke(whoami)
+
+        assert result.exit_code == 0
+        assert "Key expired. Run 'lite login --pkce' again" in result.output
+        assert "renewed on next use" not in result.output
+
     def test_whoami_no_timestamp(self):
         """Test whoami with token missing timestamp"""
         token_data = {

From 17455f4086641d829350f0ee8fb49f94e06de255 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 05:37:35 -0700
Subject: [PATCH 20/35] fix(proxy): refuse a teamless native-client grant for a
 user who has teams

The consent page offers the team picker, but a form posted without a team
sealed a teamless grant and the token endpoint minted an unscoped
credential for a team member, escaping the team attribution classic lite
login always applies. The minter now refuses such a grant on redemption
and refresh alike; memberships whose team rows are gone still count as no
team so they cannot lock a user out
---
 .../mcp_server/gateway_dcr_flow.py             |  9 +++++++--
 .../mcp_server/proxy_api_credentials.py        | 10 ++++++++--
 .../mcp_server/test_gateway_dcr_flow.py        |  1 +
 .../mcp_server/test_proxy_api_credentials.py   | 18 ++++++++++++++----
 4 files changed, 30 insertions(+), 8 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/gateway_dcr_flow.py b/litellm/proxy/_experimental/mcp_server/gateway_dcr_flow.py
index 53db6fbf9d1..bc1dea50a74 100644
--- a/litellm/proxy/_experimental/mcp_server/gateway_dcr_flow.py
+++ b/litellm/proxy/_experimental/mcp_server/gateway_dcr_flow.py
@@ -154,7 +154,7 @@ PROXY_API_AUDIENCE: Final[SessionAudience] = "proxy_api"
 proxy base URL itself as the RFC 8707 ``resource``: the grant then mints the proxy-API CLI
 credential that LLM routes accept, instead of the MCP-only session pair."""
 
-ProxyCredentialMintFailure = Literal[ReloadUserFailure, "not_a_member"]
+ProxyCredentialMintFailure = Literal[ReloadUserFailure, "not_a_member", "team_required"]
 
 
 class MintedProxyCredential(BaseModel):
@@ -167,7 +167,8 @@ class MintedProxyCredential(BaseModel):
 
 class MintProxyCredential(Protocol):
     """Injected proxy-API credential minter ``(user_id, team_id)``: reloads the user live,
-    checks team membership, and mints the same credential ``lite login`` mints."""
+    checks team membership, refuses a teamless grant for a user who has teams to pick from,
+    and mints the same credential ``lite login`` mints."""
 
     def __call__(
         self, user_id: str, team_id: str | None, /
@@ -924,6 +925,10 @@ def _mint_failure_response(failure: ProxyCredentialMintFailure) -> Response:
             return _oauth_error(
                 400, "invalid_grant", "the user is no longer a member of the team this grant was issued for"
             )
+        case "team_required":
+            return _oauth_error(
+                400, "invalid_grant", "this user belongs to a team; sign in again and pick the team for this credential"
+            )
         case "unavailable" | "unresolvable" | "no_active_key":
             return _reload_failure_response(failure)
         case _:
diff --git a/litellm/proxy/_experimental/mcp_server/proxy_api_credentials.py b/litellm/proxy/_experimental/mcp_server/proxy_api_credentials.py
index a24afc529bd..27d0ebbd5e6 100644
--- a/litellm/proxy/_experimental/mcp_server/proxy_api_credentials.py
+++ b/litellm/proxy/_experimental/mcp_server/proxy_api_credentials.py
@@ -45,7 +45,11 @@ async def mint_proxy_credential(
     live, so a team the user left between consent and redemption (or between refreshes)
     refuses the grant instead of minting a credential attributed to a team they are no
     longer on. The team is exactly the one the consent page sealed into the grant; nothing
-    is picked on the user's behalf here, so a refresh can never move the credential. The
+    is picked on the user's behalf here, so a refresh can never move the credential, and a
+    grant that names no team is refused for a user with a live team to pick from (the same
+    rule ``lite login`` applies), so a user cannot step outside their teams' attribution by
+    posting the consent form without one. Memberships whose team rows are gone count as no
+    team at all, the way ``lite login`` treats them, so they can never lock a user out. The
     user row handed to the minter carries no team list, exactly like ``lite login``'s, so
     the minter's own first-team fallback stays inert."""
     user: Final = await load_active_user_by_id(user_id)
@@ -55,9 +59,11 @@ async def mint_proxy_credential(
         return "no_active_key"
     if team_id is not None and team_id not in user.teams:
         return "not_a_member"
-    details: Final = await _team_details(user.teams) if team_id is not None else ()
+    details: Final = await _team_details(user.teams) if user.teams else ()
     if details is None:
         return "unavailable"
+    if team_id is None and any(detail.team_id is not None for detail in details):
+        return "team_required"
     selected: Final = selected_cli_sso_team_detail(details, team_id)
     if selected is None:
         return "not_a_member"
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_gateway_dcr_flow.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_gateway_dcr_flow.py
index 4e665c552f3..6c2b1274aa4 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_gateway_dcr_flow.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_gateway_dcr_flow.py
@@ -1414,6 +1414,7 @@ async def test_native_code_without_a_minter_is_refused_server_side():
     "failure, status, error",
     [
         ("not_a_member", 400, "invalid_grant"),
+        ("team_required", 400, "invalid_grant"),
         ("no_active_key", 400, "invalid_grant"),
         ("unavailable", 503, "temporarily_unavailable"),
         ("unresolvable", 500, "server_error"),
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_proxy_api_credentials.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_proxy_api_credentials.py
index 5d7c2b91046..8bb8bdada7d 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_proxy_api_credentials.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_proxy_api_credentials.py
@@ -74,16 +74,26 @@ async def test_mint_refuses_a_user_without_a_role(load_user, fetch_teams):
 
 
 @pytest.mark.asyncio
-async def test_mint_without_a_chosen_team_never_picks_one_for_a_team_member(load_user, fetch_teams):
+async def test_mint_refuses_a_teamless_grant_for_a_team_member(load_user, fetch_teams):
     """The consent page is the only place a team gets chosen, so a grant sealed without one
-    stays unscoped on every redemption and refresh instead of drifting onto the first team."""
+    is refused for a user with teams instead of minting an unscoped credential or drifting
+    onto the first team, on redemption and on every refresh alike."""
+    assert await mint_proxy_credential("u1", None) == "team_required"
+    load_user.assert_awaited_once_with("u1")
+    fetch_teams.assert_awaited_once_with(ANY, ["team-a", "team-b"])
+
+
+@pytest.mark.asyncio
+async def test_mint_for_a_member_of_only_deleted_teams_is_unscoped(load_user, fetch_teams):
+    """Memberships whose team rows are gone offer nothing to pick, so they never lock the
+    user out of signing in."""
+    load_user.return_value = _user(teams=["team-gone"])
+    fetch_teams.return_value = ()
     minted = await mint_proxy_credential("u1", None)
     assert isinstance(minted, MintedProxyCredential)
     assert minted.user_id == "u1"
     assert minted.team_id is None
     assert minted.expires_in == CLI_JWT_EXPIRATION_HOURS * 3600
-    load_user.assert_awaited_once_with("u1")
-    fetch_teams.assert_not_awaited()
     decoded = _decoded(minted)
     assert decoded.user_id == "u1"
     assert decoded.team_id is None

From e16cf5ed3ff1e7468f57186e94727c82ed278ec2 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 05:47:19 -0700
Subject: [PATCH 21/35] Fall back to the GPT version rule when the cost map
 carries no breakpoint flag

A proxy on the default remote cost map never produced a prompt cache
breakpoint: the published map has the gpt-5.6 entries without
supports_prompt_cache_breakpoint, so the model-map gate returned False
for every listed model and only LITELLM_LOCAL_MODEL_COST_MAP=True (the
repo .env, hence the passing unit tests) made the feature work. The hook
now honors the flag when the entry carries one, True or False, and
otherwise applies the GPT-5.6+ version rule to the model name, so a map
that lags the flag still gets the OpenAI dialect. The model-map tests
pin litellm.model_cost to the bundled backup map and a new test drives
the hook against an unflagged gpt-5.6 entry.

completion() and acompletion() take base_url as an alias for api_base
that only lands on api_base after the cache control hook ran, so a
GPT-5.6 call at a non-OpenAI gateway given through base_url still got
the dialect. Both seed calls and the unstamped request-params read now
look at base_url too.

ResponsesAPIRequestUtils.merge_prompt_management_input reshaped hook
output in place, retyping text parts to input_text on the caller's own
message objects. The merge now shapes a copy of each message as it
emits it, so the identity-based merge keeps working on the hook's
objects and nothing the hook or the client owns is mutated.
---
 .../anthropic_cache_control_hook.py           | 15 ++++---
 litellm/main.py                               |  4 +-
 litellm/responses/utils.py                    | 40 ++++++++++-------
 .../test_anthropic_cache_control_hook.py      | 45 ++++++++++++++++---
 .../test_responses_api_request_body.py        | 18 ++++++++
 .../responses/test_responses_utils.py         | 27 +++++++++++
 tests/test_litellm/test_main.py               | 36 +++++++++++++++
 7 files changed, 155 insertions(+), 30 deletions(-)

diff --git a/litellm/integrations/anthropic_cache_control_hook.py b/litellm/integrations/anthropic_cache_control_hook.py
index f65decc5463..1258c7593b4 100644
--- a/litellm/integrations/anthropic_cache_control_hook.py
+++ b/litellm/integrations/anthropic_cache_control_hook.py
@@ -59,10 +59,9 @@ OPENAI_API_BASE_ENV_VARS: Final = ("OPENAI_BASE_URL", "OPENAI_API_BASE")
 
 
 def supports_openai_prompt_cache_breakpoint(model: str) -> bool:
-    if _has_model_map_entry(model):
-        from litellm.utils import supports_prompt_cache_breakpoint
-
-        return supports_prompt_cache_breakpoint(model)
+    model_map_flag: Final = _model_map_prompt_cache_breakpoint_flag(model)
+    if model_map_flag is not None:
+        return model_map_flag
     version_match: Final = _GPT_VERSION_PATTERN.match(model.rsplit("/", 1)[-1].lower())
     if version_match is None:
         return False
@@ -70,10 +69,12 @@ def supports_openai_prompt_cache_breakpoint(model: str) -> bool:
     return version >= OPENAI_PROMPT_CACHE_BREAKPOINT_MIN_GPT_VERSION
 
 
-def _has_model_map_entry(model: str) -> bool:
+def _model_map_prompt_cache_breakpoint_flag(model: str) -> bool | None:
     import litellm
 
-    return model in litellm.model_cost or model.rsplit("/", 1)[-1] in litellm.model_cost
+    entries: Final = (litellm.model_cost.get(key) for key in (model, model.rsplit("/", 1)[-1]))
+    flags: Final = (entry.get("supports_prompt_cache_breakpoint") for entry in entries if isinstance(entry, dict))
+    return next((bool(flag) for flag in flags if flag is not None), None)
 
 
 def targets_openai_api(api_base: object) -> bool:
@@ -150,7 +151,7 @@ class AnthropicCacheControlHook(CustomPromptManagement):
             else AnthropicCacheControlHook._targets_openai_prompt_cache_breakpoint(
                 model,
                 non_default_params.get("custom_llm_provider"),
-                non_default_params.get("api_base"),
+                non_default_params.get("api_base") or non_default_params.get("base_url"),
                 non_default_params.get("prompt_cache_options"),
             )
         )
diff --git a/litellm/main.py b/litellm/main.py
index 87b32ab140c..98c220f94e0 100644
--- a/litellm/main.py
+++ b/litellm/main.py
@@ -507,7 +507,7 @@ async def acompletion(
         custom_llm_provider=cast(str | None, custom_llm_provider),  # cast-ok: read from untyped kwargs
         tools=tools,
         enable_prompt_caching=cast(bool | None, kwargs.get("enable_prompt_caching")),  # cast-ok: untyped kwargs
-        api_base=kwargs.get("api_base"),
+        api_base=kwargs.get("api_base") or base_url,
     )
 
     if isinstance(litellm_logging_obj, LiteLLMLoggingObj) and (
@@ -5172,7 +5172,7 @@ def completion(
         custom_llm_provider=cast(str | None, kwargs.get("custom_llm_provider")),  # cast-ok: untyped kwargs
         tools=tools,
         enable_prompt_caching=cast(bool | None, kwargs.get("enable_prompt_caching")),  # cast-ok: untyped kwargs
-        api_base=kwargs.get("api_base"),
+        api_base=kwargs.get("api_base") or base_url,
     )
 
     if isinstance(litellm_logging_obj, LiteLLMLoggingObj) and (
diff --git a/litellm/responses/utils.py b/litellm/responses/utils.py
index 504009802f2..716a815547d 100644
--- a/litellm/responses/utils.py
+++ b/litellm/responses/utils.py
@@ -37,20 +37,28 @@ def normalize_responses_api_stream_options(
     return ResponsesAPIStreamOptions(include_obfuscation=include_obfuscation)
 
 
+def _is_chat_text_part(part: object) -> bool:
+    return isinstance(part, dict) and part.get("type") == "text"
+
+
+def _as_input_text_part(part: object) -> object:
+    if isinstance(part, dict) and part.get("type") == "text":
+        return {**part, "type": "input_text"}  # mutable-ok: fresh part so the caller's block keeps its chat type
+    return part
+
+
 class ResponsesAPIRequestUtils:
     """Helper utils for constructing ResponseAPI requests"""
 
     @staticmethod
-    def shape_prompt_managed_messages_for_responses(messages: Iterable[object]) -> None:
-        for message in messages:
-            if not isinstance(message, dict) or message.get("role") == "assistant":
-                continue
-            content: object = message.get("content")
-            if not isinstance(content, list):
-                continue
-            for part in content:
-                if isinstance(part, dict) and part.get("type") == "text":
-                    part["type"] = "input_text"
+    def shape_prompt_managed_message_for_responses(message: object) -> object:
+        if not isinstance(message, dict) or message.get("role") == "assistant":
+            return message
+        content: object = message.get("content")
+        if not isinstance(content, list) or not any(_is_chat_text_part(part) for part in content):
+            return message
+        shaped_content: Final = [_as_input_text_part(part) for part in content]  # mutable-ok: Responses-shaped copy
+        return {**message, "content": shaped_content}  # mutable-ok: copy, the hook's message stays untouched
 
     @staticmethod
     def merge_prompt_management_input(
@@ -58,16 +66,16 @@ class ResponsesAPIRequestUtils:
         client_input: list[AllMessageValues],
         merged_input: list[AllMessageValues],
     ) -> list[object]:
-        ResponsesAPIRequestUtils.shape_prompt_managed_messages_for_responses(merged_input)
+        shape: Final = ResponsesAPIRequestUtils.shape_prompt_managed_message_for_responses
         if isinstance(original_input, str):
-            return [*merged_input]
+            return [shape(message) for message in merged_input]
 
         original_items: Final = tuple(original_input)
         client_item_ids: Final = frozenset(id(item) for item in client_input)
         message_positions = tuple(index for index, item in enumerate(original_items) if id(item) in client_item_ids)
 
         if len(message_positions) == len(original_items):
-            return [*merged_input]
+            return [shape(message) for message in merged_input]
         if not message_positions:
             verbose_logger.warning(
                 "Prompt management hook returned messages without Responses API input messages; merged messages were ignored"
@@ -82,7 +90,7 @@ class ResponsesAPIRequestUtils:
         if corresponding_messages:
             merged_by_position: Final = dict(zip(message_positions, merged_input))
             return [
-                merged_by_position[index] if index in merged_by_position else item
+                shape(merged_by_position[index]) if index in merged_by_position else item
                 for index, item in enumerate(original_items)
             ]
 
@@ -95,14 +103,14 @@ class ResponsesAPIRequestUtils:
                 for index, position in enumerate(message_positions)
             }
             trailing_items: Final = original_items[message_positions[-1] + 1 :]
-            return [item for merged in merged_input for item in (*prefixes.get(id(merged), ()), merged)] + list(
+            return [item for merged in merged_input for item in (*prefixes.get(id(merged), ()), shape(merged))] + list(
                 trailing_items
             )
 
         verbose_logger.warning(
             "Prompt management hook replaced Responses API messages; non-message input items were dropped"
         )
-        return [*merged_input]
+        return [shape(message) for message in merged_input]
 
     @staticmethod
     def merge_client_forwarded_headers(
diff --git a/tests/test_litellm/integrations/test_anthropic_cache_control_hook.py b/tests/test_litellm/integrations/test_anthropic_cache_control_hook.py
index 4eb774af5bc..e92a368d24b 100644
--- a/tests/test_litellm/integrations/test_anthropic_cache_control_hook.py
+++ b/tests/test_litellm/integrations/test_anthropic_cache_control_hook.py
@@ -2697,11 +2697,14 @@ class TestToolConfigSlotInOpenAIDialect:
 
 
 class TestPromptCacheBreakpointCapability:
-    """Eligibility comes from the model map's supports_prompt_cache_breakpoint flag, with the GPT version
-    rule only for models the map does not know (#37509)."""
+    """Eligibility comes from the model map's supports_prompt_cache_breakpoint flag when the entry carries one,
+    with the GPT version rule for unlisted models and for entries the published map has not flagged yet (#37509)."""
 
     @pytest.fixture(autouse=True)
-    def _fresh_model_info_cache(self):
+    def _bundled_model_map(self, monkeypatch):
+        bundled = os.path.join(os.path.dirname(litellm.__file__), "model_prices_and_context_window_backup.json")
+        with open(bundled) as handle:
+            monkeypatch.setattr(litellm, "model_cost", json.load(handle))
         litellm.utils._cached_get_model_info_helper.cache_clear()
         yield
         litellm.utils._cached_get_model_info_helper.cache_clear()
@@ -2724,15 +2727,47 @@ class TestPromptCacheBreakpointCapability:
         monkeypatch.setitem(litellm.model_cost, "gpt-4.1", flagged)
         assert supports_openai_prompt_cache_breakpoint("gpt-4.1") is True
 
-    def test_listed_gpt_5_6_without_the_flag_is_not_eligible(self, monkeypatch):
+    def test_listed_gpt_5_6_without_the_flag_falls_back_to_the_version_rule(self, monkeypatch):
         unflagged = {k: v for k, v in litellm.model_cost["gpt-5.6"].items() if k != "supports_prompt_cache_breakpoint"}
         monkeypatch.setitem(litellm.model_cost, "gpt-5.6", unflagged)
+        assert supports_openai_prompt_cache_breakpoint("gpt-5.6") is True
+        assert supports_openai_prompt_cache_breakpoint("openai/gpt-5.6") is True
+
+    def test_listed_model_flagged_false_is_not_eligible(self, monkeypatch):
+        monkeypatch.setitem(
+            litellm.model_cost, "gpt-5.6", {**litellm.model_cost["gpt-5.6"], "supports_prompt_cache_breakpoint": False}
+        )
         assert supports_openai_prompt_cache_breakpoint("gpt-5.6") is False
 
-    def test_listed_gpt_model_without_the_flag_is_false(self):
+    def test_listed_gpt_model_without_the_flag_follows_the_version_rule(self):
         assert "supports_prompt_cache_breakpoint" not in litellm.model_cost["gpt-4.1"]
         assert supports_openai_prompt_cache_breakpoint("gpt-4.1") is False
 
+    def test_published_map_without_the_flag_still_injects_on_gpt_5_6(self, monkeypatch):
+        unflagged = {k: v for k, v in litellm.model_cost["gpt-5.6"].items() if k != "supports_prompt_cache_breakpoint"}
+        monkeypatch.setitem(litellm.model_cost, "gpt-5.6", unflagged)
+        points = [{"location": "message", "role": "system"}]
+
+        _, chat_messages, chat_params = AnthropicCacheControlHook().get_chat_completion_prompt(
+            model="openai/gpt-5.6",
+            messages=[{"role": "system", "content": "sys"}, {"role": "user", "content": "hi"}],
+            non_default_params={"cache_control_injection_points": copy.deepcopy(points)},
+            prompt_id=None,
+            prompt_variables=None,
+            dynamic_callback_params={},
+        )
+        assert chat_messages[0]["content"] == [
+            {"type": "text", "text": "sys", "prompt_cache_breakpoint": {"mode": "explicit"}}
+        ]
+        assert chat_params["prompt_cache_options"] == {"mode": "explicit"}
+
+        kwargs = {"cache_control_injection_points": copy.deepcopy(points)}
+        _, system = AnthropicCacheControlHook.maybe_inject_cache_control(
+            [{"role": "user", "content": "hi"}], "sys", kwargs, model="gpt-5.6", custom_llm_provider="openai"
+        )
+        assert system == [{"type": "text", "text": "sys", "prompt_cache_breakpoint": {"mode": "explicit"}}]
+        assert kwargs == {"prompt_cache_options": {"mode": "explicit"}}
+
     @pytest.mark.parametrize("model,expected", [("gpt-5.6-2026-01-01", True), ("gpt-5.5-preview-unlisted", False)])
     def test_unlisted_model_falls_back_to_the_version_rule(self, model, expected):
         assert model not in litellm.model_cost
diff --git a/tests/test_litellm/responses/test_responses_api_request_body.py b/tests/test_litellm/responses/test_responses_api_request_body.py
index 1402491a6b6..14eb9ab6e12 100644
--- a/tests/test_litellm/responses/test_responses_api_request_body.py
+++ b/tests/test_litellm/responses/test_responses_api_request_body.py
@@ -564,6 +564,24 @@ async def test_aresponses_regional_openai_api_base_marks_input_text():
     assert body["prompt_cache_options"] == {"mode": "explicit"}
 
 
+@pytest.mark.usefixtures("_no_openai_api_base_override")
+def test_responses_custom_base_url_sends_no_openai_markers():
+    with patch("litellm.llms.custom_httpx.http_handler.HTTPHandler.post") as mock_post:
+        mock_post.return_value = MockResponse(_minimal_responses_api_payload("resp_pcb_gate_base_url", "gpt-5.6"), 200)
+
+        litellm.responses(
+            model="gpt-5.6",
+            api_key="fake-api-key",
+            base_url=_CUSTOM_API_BASE,
+            input=copy.deepcopy(_INJECTION_POINT_INPUT),
+            cache_control_injection_points=copy.deepcopy(_SYSTEM_INJECTION_POINT),
+        )
+
+        body = _sent_body(mock_post)
+        assert body["input"] == _INJECTION_POINT_INPUT
+        assert "prompt_cache_options" not in body
+
+
 @pytest.mark.usefixtures("_no_openai_api_base_override")
 def test_responses_custom_api_base_sends_no_openai_markers():
     with patch("litellm.llms.custom_httpx.http_handler.HTTPHandler.post") as mock_post:
diff --git a/tests/test_litellm/responses/test_responses_utils.py b/tests/test_litellm/responses/test_responses_utils.py
index 35bf99db6dc..2f4a699d307 100644
--- a/tests/test_litellm/responses/test_responses_utils.py
+++ b/tests/test_litellm/responses/test_responses_utils.py
@@ -671,6 +671,33 @@ class TestMergePromptManagementInputReshape:
         ]
         assert result[1] == {"role": "user", "content": "hi"}
 
+    def test_reshape_returns_copies_and_leaves_hook_output_untouched(self):
+        user_part = {"type": "text", "text": "follow-up"}
+        user_message = {"role": "user", "content": [user_part]}
+        merged = [user_message]
+
+        result = ResponsesAPIRequestUtils.merge_prompt_management_input(
+            original_input="ignored", client_input=[], merged_input=merged
+        )
+
+        assert result == [{"role": "user", "content": [{"type": "input_text", "text": "follow-up"}]}]
+        assert user_part == {"type": "text", "text": "follow-up"}
+        assert user_message == {"role": "user", "content": [user_part]}
+        assert result[0] is not user_message
+
+    def test_reshape_keeps_non_message_items_when_hook_returns_client_objects(self):
+        user_message = {"role": "user", "content": [{"type": "text", "text": "question"}]}
+        reference = {"type": "item_reference", "id": "msg_123"}
+        original_input = [reference, user_message]
+
+        result = ResponsesAPIRequestUtils.merge_prompt_management_input(
+            original_input=original_input, client_input=[user_message], merged_input=[user_message]
+        )
+
+        assert result == [reference, {"role": "user", "content": [{"type": "input_text", "text": "question"}]}]
+        assert result[0] is reference
+        assert user_message["content"] == [{"type": "text", "text": "question"}]
+
     def test_assistant_text_parts_are_left_alone(self):
         merged = [
             {"role": "assistant", "content": [{"type": "text", "text": "earlier answer"}]},
diff --git a/tests/test_litellm/test_main.py b/tests/test_litellm/test_main.py
index 786adf2d78b..4b223a3a900 100644
--- a/tests/test_litellm/test_main.py
+++ b/tests/test_litellm/test_main.py
@@ -2707,6 +2707,42 @@ def test_completion_custom_api_base_sends_no_prompt_cache_breakpoint_for_gpt_5_6
     assert "prompt_cache_options" not in json.dumps(request_body)
 
 
+@pytest.mark.usefixtures("_no_openai_api_base_override")
+def test_completion_custom_base_url_sends_no_prompt_cache_breakpoint_for_gpt_5_6():
+    from openai import OpenAI
+
+    client = OpenAI(api_key="fake-api-key", base_url="http://127.0.0.1:9/v1")
+    request_body = _openai_chat_create_kwargs(client, model="gpt-5.6", base_url="http://127.0.0.1:9/v1")
+
+    assert request_body["messages"][0] == {"role": "system", "content": "sys", "cache_control": {"type": "ephemeral"}}
+    assert "prompt_cache_breakpoint" not in json.dumps(request_body["messages"])
+    assert "prompt_cache_options" not in json.dumps(request_body)
+
+
+@pytest.mark.asyncio
+@pytest.mark.usefixtures("_no_openai_api_base_override")
+async def test_acompletion_custom_base_url_sends_no_prompt_cache_breakpoint_for_gpt_5_6():
+    from openai import AsyncOpenAI
+
+    client = AsyncOpenAI(api_key="fake-api-key", base_url="http://127.0.0.1:9/v1")
+    with patch.object(client.chat.completions.with_raw_response, "create") as mock_create:
+        with contextlib.suppress(Exception):
+            await litellm.acompletion(
+                model="gpt-5.6",
+                messages=[{"role": "system", "content": "sys"}, {"role": "user", "content": "hi"}],
+                cache_control_injection_points=[{"location": "message", "role": "system"}],
+                client=client,
+                base_url="http://127.0.0.1:9/v1",
+            )
+
+        mock_create.assert_called_once()
+        request_body = mock_create.call_args.kwargs
+
+    assert request_body["messages"][0] == {"role": "system", "content": "sys", "cache_control": {"type": "ephemeral"}}
+    assert "prompt_cache_breakpoint" not in json.dumps(request_body["messages"])
+    assert "prompt_cache_options" not in json.dumps(request_body)
+
+
 @pytest.mark.usefixtures("_no_openai_api_base_override")
 def test_completion_default_api_base_sends_prompt_cache_breakpoint_for_gpt_5_6():
     from openai import OpenAI

From 218a3ec3701c0b3354d8f28733b433b09d38373b Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 06:03:13 -0700
Subject: [PATCH 22/35] fix(cli): never follow a redirect when posting to the
 proxy's OAuth endpoints

Discovery checks that every endpoint sits on the proxy origin, but the CLI's
requests.Session followed redirects, and requests replays a POST body on
307 and 308, so a token or revocation endpoint answering with one of those
would have sent the code and verifier, or the refresh token, wherever
Location pointed. Every POST now goes out with allow_redirects=False and a
3xx answer fails the command with a message naming where it pointed
---
 .../proxy/client/cli/commands/pkce_login.py   | 28 ++++++++++++++--
 .../proxy/client/cli/test_auth_commands.py    |  2 +-
 .../proxy/client/cli/test_pkce_login.py       | 33 +++++++++++++++++--
 3 files changed, 57 insertions(+), 6 deletions(-)

diff --git a/litellm/proxy/client/cli/commands/pkce_login.py b/litellm/proxy/client/cli/commands/pkce_login.py
index 0e3b7c3271e..16d2a7b05d6 100644
--- a/litellm/proxy/client/cli/commands/pkce_login.py
+++ b/litellm/proxy/client/cli/commands/pkce_login.py
@@ -106,6 +106,7 @@ class Http(Protocol):
         data: Mapping[str, str] | None = None,
         json: Mapping[str, object] | None = None,
         timeout: float,
+        allow_redirects: bool,
     ) -> requests.Response: ...
 
 
@@ -256,6 +257,17 @@ def _form(**fields: str) -> Mapping[str, str]:
     return MappingProxyType(fields)
 
 
+def _refused_redirect(request_name: str, response: requests.Response) -> PkceFailure | None:
+    """Every POST to the proxy is sent with ``allow_redirects=False``: a 307 or 308 would make
+    ``requests`` replay the form, code and verifier or refresh token included, wherever ``Location``
+    points, past the origin check discovery passed."""
+    if not 300 <= response.status_code < 400:
+        return None
+    return PkceFailure(
+        f"{request_name} redirected to {response.headers.get('Location', 'another address')}; refusing to follow it"
+    )
+
+
 def register_client(contract: CliAuthContract, redirect_uri: str, http: Http) -> str | PkceFailure:
     registration: Final[_ClientRegistration] = {
         "client_name": _CLIENT_NAME,
@@ -265,9 +277,14 @@ def register_client(contract: CliAuthContract, redirect_uri: str, http: Http) ->
         "token_endpoint_auth_method": "none",
     }
     try:
-        response: Final = http.post(contract.registration_endpoint, json=registration, timeout=_HTTP_TIMEOUT_SECONDS)
+        response: Final = http.post(
+            contract.registration_endpoint, json=registration, timeout=_HTTP_TIMEOUT_SECONDS, allow_redirects=False
+        )
     except requests.RequestException as exc:
         return PkceFailure(f"client registration failed: {exc}")
+    redirected: Final = _refused_redirect("client registration", response)
+    if redirected is not None:
+        return redirected
     if response.status_code not in (200, 201):
         return PkceFailure(f"client registration failed with {response.status_code}: {_error_detail(response)}")
     try:
@@ -354,9 +371,12 @@ def _token_request(
     now: Callable[[], float],
 ) -> PkceCredential | PkceFailure:
     try:
-        response: Final = http.post(token_endpoint, data=form, timeout=_HTTP_TIMEOUT_SECONDS)
+        response: Final = http.post(token_endpoint, data=form, timeout=_HTTP_TIMEOUT_SECONDS, allow_redirects=False)
     except requests.RequestException as exc:
         return PkceFailure(f"token request failed: {exc}")
+    redirected: Final = _refused_redirect("token request", response)
+    if redirected is not None:
+        return redirected
     if response.status_code != 200:
         return PkceFailure(f"token request failed with {response.status_code}: {_error_detail(response)}")
     try:
@@ -382,9 +402,13 @@ def revoke_credential(revocation_endpoint: str, client_id: str, refresh_token: s
             revocation_endpoint,
             data=_form(token=refresh_token, token_type_hint="refresh_token", client_id=client_id),
             timeout=_HTTP_TIMEOUT_SECONDS,
+            allow_redirects=False,
         )
     except requests.RequestException as exc:
         return PkceFailure(f"revocation request failed: {exc}")
+    redirected: Final = _refused_redirect("revocation request", response)
+    if redirected is not None:
+        return redirected
     if response.status_code != 200:
         return PkceFailure(f"revocation failed with {response.status_code}: {_error_detail(response)}")
     return None
diff --git a/tests/test_litellm/proxy/client/cli/test_auth_commands.py b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
index 27568534bb6..0fc42e7158e 100644
--- a/tests/test_litellm/proxy/client/cli/test_auth_commands.py
+++ b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
@@ -1178,7 +1178,7 @@ class _FakeSession:
         self.response = _FakeHttpResponse(200, {})
         _FakeSession.instances.append(self)
 
-    def post(self, url, *, data=None, json=None, timeout):
+    def post(self, url, *, data=None, json=None, timeout, allow_redirects):
         self.posts.append((url, data))
         return self.response
 
diff --git a/tests/test_litellm/proxy/client/cli/test_pkce_login.py b/tests/test_litellm/proxy/client/cli/test_pkce_login.py
index db7d3c81d6c..1281de3634f 100644
--- a/tests/test_litellm/proxy/client/cli/test_pkce_login.py
+++ b/tests/test_litellm/proxy/client/cli/test_pkce_login.py
@@ -76,8 +76,9 @@ STORED = {
 
 
 class _FakeResponse:
-    def __init__(self, status_code, payload=None, text=""):
+    def __init__(self, status_code, payload=None, text="", headers=None):
         self.status_code = status_code
+        self.headers = headers or {}
         self._payload = payload
         self.text = json.dumps(payload) if payload is not None else text
         self.content = self.text.encode()
@@ -101,9 +102,12 @@ class _FakeHttp:
         self.calls.append(("GET", url, None, None))
         return self._route("GET", url, None, None)
 
-    def post(self, url, *, data=None, json=None, timeout):
+    def post(self, url, *, data=None, json=None, timeout, allow_redirects):
         self.calls.append(("POST", url, data, _wire(json)))
-        return self._route("POST", url, data, json)
+        response = self._route("POST", url, data, json)
+        if allow_redirects and 300 <= response.status_code < 400:
+            return self.post(response.headers["Location"], data=data, json=json, timeout=timeout, allow_redirects=True)
+        return response
 
     def _route(self, method, url, data, json):
         handler = self.routes[(method, url)]
@@ -404,6 +408,29 @@ def test_revoke_failures_name_the_cause(response, expected):
     assert expected in result.reason
 
 
+@pytest.mark.parametrize("status", [302, 307, 308])
+def test_posts_to_the_proxy_never_follow_a_redirect(status):
+    elsewhere = "https://evil.example.net/oauth"
+    http = _FakeHttp(
+        {
+            ("POST", f"{BASE}/register"): _FakeResponse(status, headers={"Location": elsewhere}),
+            ("POST", f"{BASE}/token"): _FakeResponse(status, headers={"Location": elsewhere}),
+            ("POST", f"{BASE}/revoke"): _FakeResponse(status, headers={"Location": elsewhere}),
+            ("POST", elsewhere): _FakeResponse(200, {"client_id": "llm_dcrc_evil", **TOKEN_JSON}),
+        }
+    )
+    outcomes = (
+        register_client(CONTRACT, "http://127.0.0.1:5/callback", http),
+        redeem_code(CONTRACT, "llm_dcrc_abc", "http://127.0.0.1:5/callback", "code", "verifier", http),
+        refresh_credential(f"{BASE}/token", f"{BASE}/revoke", BASE, "llm_dcrc_abc", "llm_srefresh_old", http),
+        revoke_credential(f"{BASE}/revoke", "llm_dcrc_abc", "llm_srefresh_old", http),
+    )
+    assert [type(outcome) for outcome in outcomes] == [PkceFailure] * 4
+    assert all(f"redirected to {elsewhere}; refusing to follow it" in outcome.reason for outcome in outcomes)
+    posted_to = [url for _, url, _, _ in http.calls]
+    assert posted_to == [f"{BASE}/register", f"{BASE}/token", f"{BASE}/token", f"{BASE}/revoke"]
+
+
 @pytest.mark.parametrize(
     "response, expected",
     [

From 39bdacb3a61429d5e85f51c016463abe45bf5904 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 06:26:57 -0700
Subject: [PATCH 23/35] fix(cli): revoke the previous login's refresh token
 when lite login replaces a stored record

---
 litellm/proxy/client/cli/commands/auth.py     |  24 +++-
 .../proxy/client/cli/test_auth_commands.py    | 113 ++++++++++++++++++
 2 files changed, 133 insertions(+), 4 deletions(-)

diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py
index b8266b7d6eb..73f69488499 100644
--- a/litellm/proxy/client/cli/commands/auth.py
+++ b/litellm/proxy/client/cli/commands/auth.py
@@ -23,6 +23,7 @@ from .claude_settings import (
     write_claude_settings,
 )
 from .pkce_login import (
+    Http,
     PkceFailure,
     fresh_api_key,
     pkce_token_record,
@@ -672,12 +673,26 @@ def _finish_login(base_url: str, api_key: str, config_claude: bool) -> None:
     show_commands()
 
 
+def _replace_stored_token(record: CliTokenData, http: Http) -> None:
+    previous: Final = load_token()
+    save_token(record)
+    if previous is None:
+        return
+    revocation: Final = revoke_stored_credential(previous, http)
+    if revocation is not None:
+        click.echo(
+            f"Could not revoke the previous login's refresh token on the proxy ({revocation.reason}); "
+            "it expires on its own."
+        )
+
+
 def _pkce_login(base_url: str, config_claude: bool) -> None:
-    credential: Final = run_pkce_login(base_url, requests.Session(), echo=click.echo)
+    http: Final = requests.Session()
+    credential: Final = run_pkce_login(base_url, http, echo=click.echo)
     if isinstance(credential, PkceFailure):
         click.echo(f"Authentication failed: {credential.reason}")
         return
-    save_token(pkce_token_record(base_url, credential))
+    _replace_stored_token(pkce_token_record(base_url, credential), http)
     _finish_login(base_url, credential.access_token, config_claude)
 
 
@@ -739,7 +754,7 @@ def login(ctx: click.Context, config_claude: bool, pkce: bool) -> None:
 
             # Save token data. base_url is stored so we can verify origin
             # before reusing the key on a subsequent CLI invocation.
-            save_token(
+            _replace_stored_token(
                 {
                     "base_url": base_url.rstrip("/"),
                     "key": api_key,
@@ -749,7 +764,8 @@ def login(ctx: click.Context, config_claude: bool, pkce: bool) -> None:
                     "auth_header_name": "Authorization",
                     "jwt_token": "",
                     "timestamp": time.time(),
-                }
+                },
+                requests.Session(),
             )
 
             _finish_login(base_url, api_key, config_claude)
diff --git a/tests/test_litellm/proxy/client/cli/test_auth_commands.py b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
index 0fc42e7158e..454cf6f8df1 100644
--- a/tests/test_litellm/proxy/client/cli/test_auth_commands.py
+++ b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
@@ -371,10 +371,50 @@ class TestTokenUtilities:
 class TestLoginCommand:
     """Test login CLI command"""
 
+    @pytest.fixture(autouse=True)
+    def isolated_home(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("USERPROFILE", str(tmp_path))
+        return tmp_path
+
     def setup_method(self):
         """Setup for each test"""
         self.runner = CliRunner()
 
+    def test_login_replaces_a_pkce_record_and_revokes_its_refresh_token(self):
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {
+            "status": "ready",
+            "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.test.jwt",
+            "user_id": "test-user-123",
+            "team_id": "team-1",
+            "teams": ["team-1"],
+        }
+        _FakeSession.instances.clear()
+
+        with (
+            patch("webbrowser.open"),
+            patch("requests.post", return_value=_mock_cli_sso_start_response()),
+            patch("requests.get", return_value=mock_response),
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _FakeSession),
+            patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=_pkce_record()),
+            patch("litellm.proxy.client.cli.commands.auth.save_token") as mock_save,
+            patch("litellm.proxy.client.cli.interface.show_commands"),
+        ):
+            result = self.runner.invoke(login, obj={"base_url": "https://test.example.com"})
+
+        assert result.exit_code == 0, result.output
+        assert "Login successful!" in result.output
+        assert "Could not revoke" not in result.output
+        assert mock_save.call_args.args[0]["key"] == "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.test.jwt"
+        assert _FakeSession.instances[0].posts == [
+            (
+                f"{PKCE_BASE_URL}/revoke",
+                {"token": "llm_srefresh_old", "token_type_hint": "refresh_token", "client_id": "llm_dcrc_abc"},
+            )
+        ]
+
     def test_login_success(self):
         """Test successful login flow with single team (JWT generated immediately)"""
         mock_context = Mock()
@@ -1237,10 +1277,83 @@ def _pkce_credential():
 class TestPkceLoginCommand:
     """``lite login --pkce`` swaps the proxy-mediated SSO poll for the browser PKCE flow."""
 
+    @pytest.fixture(autouse=True)
+    def isolated_home(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("USERPROFILE", str(tmp_path))
+        return tmp_path
+
     def setup_method(self):
         self.runner = CliRunner()
         _FakeSession.instances.clear()
 
+    def test_pkce_login_saves_the_new_record_then_revokes_the_refresh_token_it_replaced(self):
+        posts_when_saved = []
+
+        with (
+            patch("litellm.proxy.client.cli.commands.auth.run_pkce_login", return_value=_pkce_credential()),
+            patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=_pkce_record(team_id="team-a")),
+            patch(
+                "litellm.proxy.client.cli.commands.auth.save_token",
+                side_effect=lambda record: posts_when_saved.append(list(_FakeSession.instances[0].posts)),
+            ) as save,
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _FakeSession),
+            patch("litellm.proxy.client.cli.interface.show_commands"),
+        ):
+            result = self.runner.invoke(login, ["--pkce"], obj={"base_url": PKCE_BASE_URL})
+
+        assert result.exit_code == 0, result.output
+        assert "Login successful!" in result.output
+        assert "Could not revoke" not in result.output
+        assert save.call_args.args[0]["refresh_token"] == "llm_srefresh_fresh"
+        assert save.call_args.args[0]["team_id"] == "team-b"
+        assert posts_when_saved == [[]]
+        assert _FakeSession.instances[0].posts == [
+            (
+                f"{PKCE_BASE_URL}/revoke",
+                {"token": "llm_srefresh_old", "token_type_hint": "refresh_token", "client_id": "llm_dcrc_abc"},
+            )
+        ]
+
+    def test_pkce_login_keeps_the_new_record_when_the_old_refresh_token_cannot_be_revoked(self):
+        class _FailingSession(_FakeSession):
+            def __init__(self):
+                super().__init__()
+                self.response = _FakeHttpResponse(503, {"error": "temporarily_unavailable"})
+
+        with (
+            patch("litellm.proxy.client.cli.commands.auth.run_pkce_login", return_value=_pkce_credential()),
+            patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=_pkce_record()),
+            patch("litellm.proxy.client.cli.commands.auth.save_token") as save,
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _FailingSession),
+            patch("litellm.proxy.client.cli.interface.show_commands"),
+        ):
+            result = self.runner.invoke(login, ["--pkce"], obj={"base_url": PKCE_BASE_URL})
+
+        assert result.exit_code == 0, result.output
+        assert (
+            "Could not revoke the previous login's refresh token on the proxy (revocation failed with 503"
+            in result.output
+        )
+        assert "Login successful!" in result.output
+        assert save.call_args.args[0]["refresh_token"] == "llm_srefresh_fresh"
+
+    @pytest.mark.parametrize("previous", [None, {"key": "sk-classic", "base_url": PKCE_BASE_URL}])
+    def test_pkce_login_without_a_previous_refresh_token_makes_no_revocation_request(self, previous):
+        with (
+            patch("litellm.proxy.client.cli.commands.auth.run_pkce_login", return_value=_pkce_credential()),
+            patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=previous),
+            patch("litellm.proxy.client.cli.commands.auth.save_token") as save,
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _FakeSession),
+            patch("litellm.proxy.client.cli.interface.show_commands"),
+        ):
+            result = self.runner.invoke(login, ["--pkce"], obj={"base_url": PKCE_BASE_URL})
+
+        assert result.exit_code == 0, result.output
+        assert "Login successful!" in result.output
+        save.assert_called_once()
+        assert _FakeSession.instances[0].posts == []
+
     def test_pkce_login_saves_the_refreshable_record_and_skips_the_sso_poll(self):
         with (
             patch("litellm.proxy.client.cli.commands.auth.run_pkce_login", return_value=_pkce_credential()) as run,

From 44d3fc7ec80432f68e8b4564b2b192c06f7d968b Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 07:21:42 -0700
Subject: [PATCH 24/35] fix(cli): name lite login --pkce and the refresh
 failure when a key cannot be renewed

A PKCE credential whose renewal is refused (for example after lite logout ran
on another copy of it) used to fail lite auth print-token with the classic
'Token expired. Run lite login again' hint and no reason, while lite whoami
already named lite login --pkce. fresh_api_key now reports why a renewal
failed through a warn callback whenever no sibling rotation rescued it, the
CLI prints that reason on stderr, and the expiry hint names the command that
produced the credential. Both READMEs document the admin revocation semantics
and the Redis precondition for refresh single use on several workers.
---
 litellm/proxy/client/README.md                |  2 +-
 litellm/proxy/client/cli/README.md            |  2 +-
 litellm/proxy/client/cli/commands/auth.py     | 24 +++++++++++++------
 .../proxy/client/cli/commands/pkce_login.py   | 16 ++++++++++---
 .../proxy/client/cli/test_auth_commands.py    | 24 ++++++++++++++++++-
 .../proxy/client/cli/test_pkce_login.py       | 14 +++++++++++
 6 files changed, 69 insertions(+), 13 deletions(-)

diff --git a/litellm/proxy/client/README.md b/litellm/proxy/client/README.md
index 997c923de4d..bfe95dfcbd7 100644
--- a/litellm/proxy/client/README.md
+++ b/litellm/proxy/client/README.md
@@ -378,7 +378,7 @@ Authentication tokens are stored in `~/.litellm/token.json` with restricted file
 }
 ```
 
-The stored credential is a short-lived, per-session agent token, not a managed virtual key. It is scoped to the user and team you logged in as and inherits their models and budgets; spend is tracked against the shared team and user budgets rather than a separate per-session cap, so multiple logins or several concurrent agents all draw down the same allowance. It is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); re-run `lite login` to refresh it and pick up your latest team and user settings. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it while fresh and fails once it expires -- there is no silent renewal. It is accepted on a default deployment without `EXPERIMENTAL_UI_LOGIN`, does not appear in the Keys UI, and cannot be rotated or revoked mid-session. A credential from `lite login --pkce` is the exception: it carries a refresh token, so the CLI renews the key shortly before it expires and `lite logout` revokes the refresh token on the proxy (see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). For a long-lived, rotatable, Keys-UI-visible credential, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY`.
+The stored credential is a short-lived, per-session agent token, not a managed virtual key. It is scoped to the user and team you logged in as and inherits their models and budgets; spend is tracked against the shared team and user budgets rather than a separate per-session cap, so multiple logins or several concurrent agents all draw down the same allowance. It is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); re-run `lite login` to refresh it and pick up your latest team and user settings. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it while fresh and fails once it expires -- there is no silent renewal. It is accepted on a default deployment without `EXPERIMENTAL_UI_LOGIN`, does not appear in the Keys UI, and cannot be rotated or revoked mid-session. A credential from `lite login --pkce` is the exception: it carries a refresh token, so the CLI renews the key shortly before it expires and `lite logout` revokes the refresh token on the proxy (see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). Only the holder can end a `--pkce` session early, with `lite logout`; an admin has no button for it, but every renewal re-reads the user on the proxy, so deactivating the user or removing them from the team makes the next renewal fail and the key runs out within `LITELLM_CLI_JWT_EXPIRATION_HOURS`. On a proxy with more than one worker or replica, configure Redis (`litellm_settings.cache` with Redis `cache_params`, or `general_settings.coordination_redis`) so a refresh token stays single-use and `lite logout` holds on every worker; without Redis each worker keeps its own record. For a long-lived, rotatable, Keys-UI-visible credential, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY`.
 
 ### Usage
 
diff --git a/litellm/proxy/client/cli/README.md b/litellm/proxy/client/cli/README.md
index faa015a2f77..fe417396317 100644
--- a/litellm/proxy/client/cli/README.md
+++ b/litellm/proxy/client/cli/README.md
@@ -501,7 +501,7 @@ To pin the model, pass the agent's own model flag (for example `lite claude --mo
 
 The token minted by `lite login` is a short-lived, per-session agent credential, not a managed virtual key. It is scoped to the user and team you authenticated as, inherits that user's and team's models and budgets, and is enforced on the proxy exactly like a virtual key on the same team (guardrails, routing, logging, spend). Spend is tracked against the shared team and user budgets, so running several agents (or logging in more than once) does not hand each session its own separate budget; they all draw down the same team/user allowance. There is no separate per-session cap, so sustained agent use is not capped at a small chat-session limit.
 
-The credential is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); run `lite login` again to refresh it, which also re-reads your latest team and user settings. It does not appear in the Keys UI and cannot be rotated or revoked mid-session. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it while it's still fresh and fails once it expires -- there is no silent renewal, so a long-running session needs a fresh `lite login` once a day. `lite claude`, `lite codex`, and `lite opencode` work with it on a default deployment; `EXPERIMENTAL_UI_LOGIN` is not required. `lite login --pkce` is the exception to the daily re-login: it signs in through your system browser with OAuth authorization code and PKCE and stores a refresh token next to the key, so every `lite` command and `lite auth print-token` renew the key on their own shortly before it expires, `lite whoami` shows when the current key expires, and `lite logout` revokes the refresh token on the proxy (it needs a proxy that serves `/.well-known/litellm-cli-auth`; see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). If you need a long-lived, rotatable key that shows up in the Keys UI, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY` instead.
+The credential is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); run `lite login` again to refresh it, which also re-reads your latest team and user settings. It does not appear in the Keys UI and cannot be rotated or revoked mid-session. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it while it's still fresh and fails once it expires -- there is no silent renewal, so a long-running session needs a fresh `lite login` once a day. `lite claude`, `lite codex`, and `lite opencode` work with it on a default deployment; `EXPERIMENTAL_UI_LOGIN` is not required. `lite login --pkce` is the exception to the daily re-login: it signs in through your system browser with OAuth authorization code and PKCE and stores a refresh token next to the key, so every `lite` command and `lite auth print-token` renew the key on their own shortly before it expires, `lite whoami` shows when the current key expires, and `lite logout` revokes the refresh token on the proxy (it needs a proxy that serves `/.well-known/litellm-cli-auth`; see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). When a renewal is refused, for example after a `lite logout` run from another copy of the credential, the command prints why on stderr and, once the key has run out, tells you to run `lite login --pkce` again. Only the holder can end a `--pkce` session early, with `lite logout`; an admin has no button for it, but every renewal re-reads the user on the proxy, so deactivating the user or removing them from the team makes the next renewal fail and the key runs out within `LITELLM_CLI_JWT_EXPIRATION_HOURS`. On a proxy with more than one worker or replica, configure Redis (`litellm_settings.cache` with Redis `cache_params`, or `general_settings.coordination_redis`) so a refresh token stays single-use and `lite logout` holds on every worker; without Redis each worker keeps its own record. If you need a long-lived, rotatable key that shows up in the Keys UI, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY` instead.
 
 ### Route Every Claude Code Session Through the Proxy
 
diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py
index 73f69488499..d776a2c9418 100644
--- a/litellm/proxy/client/cli/commands/auth.py
+++ b/litellm/proxy/client/cli/commands/auth.py
@@ -135,7 +135,15 @@ def get_stored_api_key(expected_base_url: str | None = None) -> str | None:
         return None
     if expected_base_url is not None and token_data.get("base_url") != expected_base_url.rstrip("/"):
         return None
-    return fresh_api_key(token_data, save_token, requests.Session(), reload=load_token)
+    return fresh_api_key(token_data, save_token, requests.Session(), reload=load_token, warn=_warn)
+
+
+def _warn(message: str) -> None:
+    click.echo(message, err=True)
+
+
+def _login_command(renews: bool) -> str:
+    return "lite login --pkce" if renews else "lite login"
 
 
 # Team selection utilities
@@ -809,8 +817,9 @@ def print_token(ctx: click.Context):
     Designed to be used as Claude Code's `apiKeyHelper`
     (https://docs.claude.com/en/docs/claude-code/settings): stdout must
     contain only the token, so all diagnostics go to stderr. The token
-    expires after `LITELLM_CLI_JWT_EXPIRATION_HOURS` (default 24h); once
-    expired, run `lite login` again.
+    expires after `LITELLM_CLI_JWT_EXPIRATION_HOURS` (default 24h); a
+    `lite login --pkce` token renews itself here first, and once a token
+    has expired for good, run the same `lite login` command again.
     """
     token_data: Final = load_token()
     if not token_data:
@@ -828,13 +837,14 @@ def print_token(ctx: click.Context):
             click.echo("Not authenticated for this server. Run 'lite login'.", err=True)
             sys.exit(1)
 
-    if not is_cli_token_fresh(token_data) and "refresh_token" not in token_data:
+    renews: Final = "refresh_token" in token_data
+    if not is_cli_token_fresh(token_data) and not renews:
         click.echo("Token expired. Run 'lite login' again.", err=True)
         sys.exit(1)
 
-    api_key: Final = fresh_api_key(token_data, save_token, requests.Session(), reload=load_token)
+    api_key: Final = fresh_api_key(token_data, save_token, requests.Session(), reload=load_token, warn=_warn)
     if not api_key:
-        click.echo("Token expired. Run 'lite login' again.", err=True)
+        click.echo(f"Key expired. Run '{_login_command(renews)}' again.", err=True)
         sys.exit(1)
 
     click.echo(api_key)
@@ -871,7 +881,7 @@ def whoami():
 def _key_expiry_line(expires_at: float, renews: bool) -> str:
     remaining_hours: Final = (expires_at - time.time()) / 3600
     if remaining_hours <= 0:
-        return f"Key expired. Run '{'lite login --pkce' if renews else 'lite login'}' again"
+        return f"Key expired. Run '{_login_command(renews)}' again"
     status: Final = f"Key expires in: {remaining_hours:.1f} hours"
     return f"{status}, renewed on next use" if renews else status
 
diff --git a/litellm/proxy/client/cli/commands/pkce_login.py b/litellm/proxy/client/cli/commands/pkce_login.py
index 16d2a7b05d6..a0db1ba2db7 100644
--- a/litellm/proxy/client/cli/commands/pkce_login.py
+++ b/litellm/proxy/client/cli/commands/pkce_login.py
@@ -476,6 +476,10 @@ def pkce_token_record(base_url: str, credential: PkceCredential) -> CliTokenData
     return record
 
 
+def _ignore_warning(_message: str) -> None:
+    return None
+
+
 def fresh_api_key(
     token_data: Mapping[str, object],
     save: Callable[[CliTokenData], None],
@@ -483,6 +487,7 @@ def fresh_api_key(
     *,
     reload: Callable[[], Mapping[str, object] | None],
     now: Callable[[], float] = time.time,
+    warn: Callable[[str], None] = _ignore_warning,
 ) -> str | None:
     """The stored key, refreshed first when it is about to expire and a refresh token is
     on file. The refresh fires at the same moment ``is_cli_token_fresh`` stops calling the
@@ -490,8 +495,10 @@ def fresh_api_key(
     with itself. The rotated pair is saved before the new key is returned, so a crash after
     this point never strands the CLI with a burned refresh token. A refresh that fails
     reads the record again, because a sibling ``lite`` process may have rotated the pair
-    first, in which case the key it saved for this same proxy is the live one. A record without
-    ``expires_at`` (the classic ``lite login`` credential) is returned as stored."""
+    first, in which case the key it saved for this same proxy is the live one; when no sibling
+    did, the reason the proxy gave goes to ``warn`` so a revoked or refused refresh token is
+    never a silent failure. A record without ``expires_at`` (the classic ``lite login``
+    credential) is returned as stored."""
     key: Final = token_data.get("key")
     if not isinstance(key, str) or not key:
         return None
@@ -506,7 +513,10 @@ def fresh_api_key(
         return still_valid
     refreshed: Final = refresh_credential(*refresh_inputs, http=http, now=now)
     if isinstance(refreshed, PkceFailure):
-        return _key_rotated_by_a_sibling(reload(), token_data, now()) or still_valid
+        sibling_key: Final = _key_rotated_by_a_sibling(reload(), token_data, now())
+        if sibling_key is None:
+            warn(f"Could not renew the key: {refreshed.reason}")
+        return sibling_key or still_valid
     base_url: Final = token_data.get("base_url")
     save(pkce_token_record(base_url if isinstance(base_url, str) else "", refreshed))
     return refreshed.access_token
diff --git a/tests/test_litellm/proxy/client/cli/test_auth_commands.py b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
index 454cf6f8df1..f618bf8ea61 100644
--- a/tests/test_litellm/proxy/client/cli/test_auth_commands.py
+++ b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
@@ -1520,7 +1520,9 @@ class TestPkcePrintToken:
 
         assert result.exit_code == 1
         assert result.stdout == ""
-        assert "Token expired. Run 'lite login' again." in result.output
+        assert "Could not renew the key: token request failed with 400: invalid_grant" in result.output
+        assert "Key expired. Run 'lite login --pkce' again." in result.output
+        assert "Run 'lite login' again" not in result.output
         save.assert_not_called()
 
     def test_print_token_for_an_expired_classic_token_makes_no_request(self):
@@ -1557,3 +1559,23 @@ class TestGetStoredApiKeyRefresh:
 
         assert save.call_count == 1
         assert len(_FakeSession.instances) == 1
+
+    def test_get_stored_api_key_reports_a_refused_renewal_on_stderr_and_keeps_the_valid_key(self, capsys):
+        _FakeSession.instances.clear()
+
+        class _RefusingSession(_FakeSession):
+            def __init__(self):
+                super().__init__()
+                self.response = _FakeHttpResponse(503, {"error": "temporarily_unavailable"})
+
+        with (
+            patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=_pkce_record()),
+            patch("litellm.proxy.client.cli.commands.auth.save_token") as save,
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _RefusingSession),
+        ):
+            assert get_stored_api_key(PKCE_BASE_URL) == "sk-cli-old"
+
+        captured = capsys.readouterr()
+        assert captured.out == ""
+        assert captured.err == "Could not renew the key: token request failed with 503: temporarily_unavailable\n"
+        save.assert_not_called()
diff --git a/tests/test_litellm/proxy/client/cli/test_pkce_login.py b/tests/test_litellm/proxy/client/cli/test_pkce_login.py
index 1281de3634f..712c7e83236 100644
--- a/tests/test_litellm/proxy/client/cli/test_pkce_login.py
+++ b/tests/test_litellm/proxy/client/cli/test_pkce_login.py
@@ -619,6 +619,20 @@ def test_fresh_api_key_falls_back_to_the_old_key_only_while_it_is_still_valid():
     assert saved == []
 
 
+def test_fresh_api_key_reports_why_a_renewal_failed_unless_a_sibling_rotated_first():
+    failing = _FakeHttp({("POST", f"{BASE}/token"): _FakeResponse(503, {"error": "temporarily_unavailable"})})
+    rotated = {**STORED, "key": "sk-cli-sibling", "refresh_token": "llm_srefresh_sibling", "expires_at": 1_003_600.0}
+    warnings = []
+    assert _fresh(STORED, lambda _: None, failing, now=lambda: 990_000.0, warn=warnings.append) == "sk-cli-old"
+    assert warnings == []
+    assert _fresh(STORED, lambda _: None, failing, now=lambda: 999_950.0, warn=warnings.append) == "sk-cli-old"
+    assert _fresh(STORED, lambda _: None, failing, now=lambda: 1_000_001.0, warn=warnings.append) is None
+    assert warnings == ["Could not renew the key: token request failed with 503: temporarily_unavailable"] * 2
+    sibling = _fresh(STORED, lambda _: None, failing, reload=lambda: rotated, now=lambda: 1_000_001.0, warn=warnings.append)
+    assert sibling == "sk-cli-sibling"
+    assert len(warnings) == 2
+
+
 def test_fresh_api_key_uses_a_sibling_rotation_when_its_own_refresh_loses_the_race():
     rotated = {**STORED, "key": "sk-cli-sibling", "refresh_token": "llm_srefresh_sibling", "expires_at": 1_003_600.0}
     http = _FakeHttp({("POST", f"{BASE}/token"): _FakeResponse(400, {"error": "invalid_grant"})})

From 36e9e813a7339e8182adc10d457aea6250b09248 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 07:29:04 -0700
Subject: [PATCH 25/35] fix(cli): renew the key once per lite auth print-token
 run

The cli group already resolves the stored key for the server it was pointed
at, so print-token re-ran the renewal and, when the refresh token had been
revoked, posted to /token twice and printed the reason twice. print-token now
reuses the group's result whenever the stored record was issued for that
server and no --api-key or LITELLM_PROXY_API_KEY took precedence, and only
resolves the key itself when invoked bare for a different server.
---
 litellm/proxy/client/cli/commands/auth.py     | 17 +++---
 litellm/proxy/client/cli/main.py              |  9 ++--
 .../proxy/client/cli/test_auth_commands.py    | 52 +++++++++++++++++++
 3 files changed, 68 insertions(+), 10 deletions(-)

diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py
index d776a2c9418..4eb23a547b6 100644
--- a/litellm/proxy/client/cli/commands/auth.py
+++ b/litellm/proxy/client/cli/commands/auth.py
@@ -61,6 +61,8 @@ class CliTeam(TypedDict, total=False):
 class CliContextObj(TypedDict):
     base_url: str
     base_url_explicit: NotRequired[bool]
+    api_key: ReadOnly[NotRequired[str | None]]
+    api_key_from_token_file: ReadOnly[NotRequired[bool]]
 
 
 class CliPollData(TypedDict, total=False):
@@ -831,18 +833,21 @@ def print_token(ctx: click.Context):
     # actually issued this token for -- that's the whole point of not
     # needing a wrapper command.
     ctx_obj: Final[CliContextObj] = ctx.obj
-    if ctx_obj.get("base_url_explicit"):
-        base_url: Final = ctx_obj["base_url"]
-        if token_data.get("base_url") != base_url.rstrip("/"):
-            click.echo("Not authenticated for this server. Run 'lite login'.", err=True)
-            sys.exit(1)
+    issued_for_this_server: Final = token_data.get("base_url") == ctx_obj.get("base_url", "").rstrip("/")
+    if ctx_obj.get("base_url_explicit") and not issued_for_this_server:
+        click.echo("Not authenticated for this server. Run 'lite login'.", err=True)
+        sys.exit(1)
 
     renews: Final = "refresh_token" in token_data
     if not is_cli_token_fresh(token_data) and not renews:
         click.echo("Token expired. Run 'lite login' again.", err=True)
         sys.exit(1)
 
-    api_key: Final = fresh_api_key(token_data, save_token, requests.Session(), reload=load_token, warn=_warn)
+    api_key: Final = (
+        ctx_obj.get("api_key")
+        if issued_for_this_server and ctx_obj.get("api_key_from_token_file")
+        else fresh_api_key(token_data, save_token, requests.Session(), reload=load_token, warn=_warn)
+    )
     if not api_key:
         click.echo(f"Key expired. Run '{_login_command(renews)}' again.", err=True)
         sys.exit(1)
diff --git a/litellm/proxy/client/cli/main.py b/litellm/proxy/client/cli/main.py
index 3a289736c66..6dba1399acb 100644
--- a/litellm/proxy/client/cli/main.py
+++ b/litellm/proxy/client/cli/main.py
@@ -93,11 +93,12 @@ def cli(ctx: click.Context, show_version: bool, base_url: str | None, api_key: s
 
     # If no API key provided via flag or environment variable, try to load from saved token.
     # Pass base_url so we only use the stored key when it was issued for this server.
-    if api_key is None:
-        api_key = get_stored_api_key(expected_base_url=base_url)
+    api_key_from_token_file: Final = api_key is None
+    resolved_api_key: Final = get_stored_api_key(expected_base_url=base_url) if api_key_from_token_file else api_key
 
     ctx.obj["base_url"] = base_url
-    ctx.obj["api_key"] = api_key
+    ctx.obj["api_key"] = resolved_api_key
+    ctx.obj["api_key_from_token_file"] = api_key_from_token_file
     # `--base-url` defaults to localhost:4000 for local dev convenience, but
     # apiKeyHelper is invoked bare (no flags) -- commands that must work
     # unattended (print-token) need to tell "user didn't say" apart from
@@ -107,7 +108,7 @@ def cli(ctx: click.Context, show_version: bool, base_url: str | None, api_key: s
     ctx.obj["base_url_explicit"] = base_url_provided or bool(stored_base_url)
 
     if show_version:
-        print_version(base_url, api_key)
+        print_version(base_url, resolved_api_key)
         ctx.exit()
 
     # If no subcommand was invoked, start interactive mode
diff --git a/tests/test_litellm/proxy/client/cli/test_auth_commands.py b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
index f618bf8ea61..9b7dbbd1fdd 100644
--- a/tests/test_litellm/proxy/client/cli/test_auth_commands.py
+++ b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
@@ -1525,6 +1525,58 @@ class TestPkcePrintToken:
         assert "Run 'lite login' again" not in result.output
         save.assert_not_called()
 
+    def test_print_token_through_the_cli_group_renews_once_and_reports_a_refusal_once(self, monkeypatch):
+        monkeypatch.delenv("LITELLM_PROXY_API_KEY", raising=False)
+        monkeypatch.delenv("LITELLM_PROXY_URL", raising=False)
+
+        class _RefusingSession(_FakeSession):
+            def __init__(self):
+                super().__init__()
+                self.response = _FakeHttpResponse(
+                    400, {"error": "invalid_grant", "error_description": "the refresh token was already used"}
+                )
+
+        with (
+            patch(
+                "litellm.proxy.client.cli.commands.auth.load_token",
+                return_value=_pkce_record(expires_at=time.time() - 1),
+            ),
+            patch("litellm.proxy.client.cli.commands.auth.save_token") as save,
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _RefusingSession),
+        ):
+            result = self.runner.invoke(cli, ["--base-url", PKCE_BASE_URL, "auth", "print-token"])
+
+        assert result.exit_code == 1
+        assert result.stdout == ""
+        assert sum(len(session.posts) for session in _FakeSession.instances) == 1
+        assert result.output.count("Could not renew the key") == 1
+        assert "Could not renew the key: token request failed with 400: the refresh token was already used" in result.output
+        assert "Key expired. Run 'lite login --pkce' again." in result.output
+        save.assert_not_called()
+
+    def test_print_token_invoked_bare_for_another_server_renews_once(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("USERPROFILE", str(tmp_path))
+        monkeypatch.delenv("LITELLM_PROXY_API_KEY", raising=False)
+        monkeypatch.delenv("LITELLM_PROXY_URL", raising=False)
+
+        class _RefreshingSession(_FakeSession):
+            def __init__(self):
+                super().__init__()
+                self.response = _FakeHttpResponse(200, PKCE_TOKEN_RESPONSE)
+
+        with (
+            patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=_pkce_record()),
+            patch("litellm.proxy.client.cli.commands.auth.save_token") as save,
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _RefreshingSession),
+        ):
+            result = self.runner.invoke(cli, ["auth", "print-token"])
+
+        assert result.exit_code == 0, result.output
+        assert result.stdout == "sk-cli-rotated\n"
+        assert sum(len(session.posts) for session in _FakeSession.instances) == 1
+        assert save.call_count == 1
+
     def test_print_token_for_an_expired_classic_token_makes_no_request(self):
         with (
             patch(

From a20cfc5f0e5d8a83764e7b49775bd0fb98b631d1 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 07:40:17 -0700
Subject: [PATCH 26/35] fix(cli): let lite up trust the key the group already
 renewed

The lite group resolves the stored key once for every command and renews a --pkce key on the way in. lite up then asked the token file again, so every start sent a second refresh to the proxy, and once the refresh token was burned the refusal printed twice. _ensure_fresh_login now reuses the key the group resolved when the group read it from the token file, and only re-reads the file after the interactive login it starts itself. Also covers print-token through the group with a renewing session in the tests
---
 litellm/proxy/client/cli/commands/up.py       | 19 +++++---
 .../proxy/client/cli/test_auth_commands.py    | 21 +++++++++
 .../proxy/client/cli/test_up_commands.py      | 46 +++++++++++++++++++
 3 files changed, 80 insertions(+), 6 deletions(-)

diff --git a/litellm/proxy/client/cli/commands/up.py b/litellm/proxy/client/cli/commands/up.py
index 35ca504c493..80b7a04b75a 100644
--- a/litellm/proxy/client/cli/commands/up.py
+++ b/litellm/proxy/client/cli/commands/up.py
@@ -17,7 +17,7 @@ from pydantic import JsonValue, TypeAdapter, ValidationError
 from litellm.litellm_core_utils.cli_token_utils import is_cli_token_fresh
 
 from .agents import AgentRunError, resolve_api_key, verify_proxy_key
-from .auth import get_stored_api_key, load_token, login
+from .auth import CliContextObj, get_stored_api_key, load_token, login
 from .claude_settings import (
     BACKUP_PATH,
     CLAUDE_SETTINGS_PATH,
@@ -103,21 +103,28 @@ def restore_claude_settings(settings_path: Path | None = None, backup_path: Path
     return record
 
 
-def _usable_login(base_url: str) -> bool:
-    if get_stored_api_key(expected_base_url=base_url) is None:
+def _usable_login(api_key: str | None) -> bool:
+    if api_key is None:
         return False
     token_data: Final = load_token()
     return token_data is not None and is_cli_token_fresh(token_data)
 
 
+def _key_resolved_on_the_way_in(ctx_obj: CliContextObj, base_url: str) -> str | None:
+    if ctx_obj.get("api_key_from_token_file"):
+        return ctx_obj.get("api_key")
+    return get_stored_api_key(expected_base_url=base_url)
+
+
 def _stored_login_is_pkce() -> bool:
     token_data: Final = load_token()
     return token_data is not None and "refresh_token" in token_data
 
 
 def _ensure_fresh_login(ctx: click.Context) -> None:
-    base_url: Final = ctx.obj["base_url"].rstrip("/")
-    if _usable_login(base_url):
+    ctx_obj: Final[CliContextObj] = ctx.obj
+    base_url: Final = ctx_obj["base_url"].rstrip("/")
+    if _usable_login(_key_resolved_on_the_way_in(ctx_obj, base_url)):
         return
 
     pkce: Final = _stored_login_is_pkce()
@@ -130,7 +137,7 @@ def _ensure_fresh_login(ctx: click.Context) -> None:
 
     click.echo("No fresh LiteLLM login found for this proxy; starting login...")
     ctx.invoke(login, pkce=pkce)
-    if not _usable_login(base_url):
+    if not _usable_login(get_stored_api_key(expected_base_url=base_url)):
         raise UpError("Login did not produce a usable token; cannot start `lite up`.")
 
 
diff --git a/tests/test_litellm/proxy/client/cli/test_auth_commands.py b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
index 9b7dbbd1fdd..f6123b5c690 100644
--- a/tests/test_litellm/proxy/client/cli/test_auth_commands.py
+++ b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
@@ -1554,6 +1554,27 @@ class TestPkcePrintToken:
         assert "Key expired. Run 'lite login --pkce' again." in result.output
         save.assert_not_called()
 
+    def test_print_token_through_the_cli_group_prints_the_key_the_group_renewed(self, monkeypatch):
+        monkeypatch.delenv("LITELLM_PROXY_API_KEY", raising=False)
+        monkeypatch.delenv("LITELLM_PROXY_URL", raising=False)
+
+        class _RefreshingSession(_FakeSession):
+            def __init__(self):
+                super().__init__()
+                self.response = _FakeHttpResponse(200, PKCE_TOKEN_RESPONSE)
+
+        with (
+            patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=_pkce_record()),
+            patch("litellm.proxy.client.cli.commands.auth.save_token") as save,
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _RefreshingSession),
+        ):
+            result = self.runner.invoke(cli, ["--base-url", PKCE_BASE_URL, "auth", "print-token"])
+
+        assert result.exit_code == 0, result.output
+        assert result.stdout == "sk-cli-rotated\n"
+        assert sum(len(session.posts) for session in _FakeSession.instances) == 1
+        assert save.call_count == 1
+
     def test_print_token_invoked_bare_for_another_server_renews_once(self, monkeypatch, tmp_path):
         monkeypatch.setenv("HOME", str(tmp_path))
         monkeypatch.setenv("USERPROFILE", str(tmp_path))
diff --git a/tests/test_litellm/proxy/client/cli/test_up_commands.py b/tests/test_litellm/proxy/client/cli/test_up_commands.py
index 6344e4ba154..264de328c37 100644
--- a/tests/test_litellm/proxy/client/cli/test_up_commands.py
+++ b/tests/test_litellm/proxy/client/cli/test_up_commands.py
@@ -221,6 +221,13 @@ def _make_ctx(base_url):
     return click.Context(click.Command("test"), obj={"base_url": base_url})
 
 
+def _make_group_ctx(base_url, api_key):
+    """The context the `lite` group hands down after it already read the token file once."""
+    return click.Context(
+        click.Command("test"), obj={"base_url": base_url, "api_key": api_key, "api_key_from_token_file": True}
+    )
+
+
 def _pkce_record(base_url, seconds_left):
     return {
         "key": "sk-pkce",
@@ -339,6 +346,45 @@ class TestEnsureFreshLogin:
         with pytest.raises(UpError, match="Run `lite login --pkce` first"):
             _ensure_fresh_login(_make_ctx("http://proxy-a:4000"))
 
+    def test_trusts_the_key_the_cli_group_already_resolved_instead_of_reading_the_token_file_again(
+        self, monkeypatch
+    ):
+        """The `lite` group renews a --pkce key on the way in, so a second renewal here would hit
+        the proxy twice and, once the refresh token is burned, print the refusal twice."""
+        store = _FakeTokenStore(monkeypatch, _pkce_record("http://proxy-a:4000", seconds_left=86_400), {})
+        login_calls = _capture_login(monkeypatch)
+
+        _ensure_fresh_login(_make_group_ctx("http://proxy-a:4000", api_key="sk-pkce-renewed-by-the-group"))
+
+        assert login_calls == []
+        assert store.key_requests == []
+
+    def test_fails_non_interactively_without_a_second_renewal_when_the_group_could_not_renew(self, monkeypatch):
+        monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: False)
+        store = _FakeTokenStore(
+            monkeypatch,
+            _pkce_record("http://proxy-a:4000", seconds_left=-10),
+            {"http://proxy-a:4000": "sk-a-second-renewal-would-mint-this"},
+        )
+
+        with pytest.raises(UpError, match="Run `lite login --pkce` first"):
+            _ensure_fresh_login(_make_group_ctx("http://proxy-a:4000", api_key=None))
+
+        assert store.key_requests == []
+
+    def test_re_reads_the_token_file_only_after_the_interactive_login_it_started(self, monkeypatch):
+        monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True)
+        store = _FakeTokenStore(monkeypatch, _pkce_record("http://proxy-a:4000", seconds_left=-10), {})
+        login_calls = _capture_login(
+            monkeypatch,
+            on_login=lambda: store.log_in(_pkce_record("http://proxy-a:4000", seconds_left=86_400), "sk-pkce-fresh"),
+        )
+
+        _ensure_fresh_login(_make_group_ctx("http://proxy-a:4000", api_key=None))
+
+        assert login_calls == [("http://proxy-a:4000", True)]
+        assert store.key_requests == ["http://proxy-a:4000"]
+
 
 class TestUpCommand:
     def setup_method(self):

From 238609ea5db223ee977dc4de9e677787801d3af1 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 07:56:38 -0700
Subject: [PATCH 27/35] fix(mcp): answer 503 when a refresh-token burn cannot
 be recorded

revoke_refresh_token discarded the single-use claim result, so a revocation that arrived while Redis was unreachable answered 200 and left the refresh token live. The token endpoint reported the same outage as invalid_grant "already used". The guard now reports first, replayed, or unavailable, and both endpoints answer 503 temporarily_unavailable for an outage (RFC 7009 section 2.2.1, RFC 6749 section 5.2), which the CLI surfaces as a one-line warning while keeping the key it has
---
 .../mcp_server/gateway_dcr_flow.py            | 72 +++++++++++----
 .../mcp_server/test_gateway_dcr_flow.py       | 92 ++++++++++++++++++-
 2 files changed, 143 insertions(+), 21 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/gateway_dcr_flow.py b/litellm/proxy/_experimental/mcp_server/gateway_dcr_flow.py
index bc1dea50a74..314c80adbc4 100644
--- a/litellm/proxy/_experimental/mcp_server/gateway_dcr_flow.py
+++ b/litellm/proxy/_experimental/mcp_server/gateway_dcr_flow.py
@@ -723,10 +723,16 @@ async def complete_connect_flow(
         return _oauth_error(401, "login_required", "sign in to LiteLLM to finish connecting")
     if session_user_id != flow.user_id:
         return _oauth_error(403, "access_denied", "the signed-in user does not match this connect flow")
-    if not await _SingleUseGuard(cache).claim(
-        f"{_USED_FLOW_CACHE_PREFIX}{flow.jti}", CONNECT_FLOW_TTL_SECONDS + _CLAIM_TTL_BUFFER_SECONDS
-    ):
-        return _oauth_error(400, "invalid_request", "this connect flow was already completed; restart the connection")
+    flow_refusal: Final = _claim_refusal(
+        await _SingleUseGuard(cache).claim(
+            f"{_USED_FLOW_CACHE_PREFIX}{flow.jti}", CONNECT_FLOW_TTL_SECONDS + _CLAIM_TTL_BUFFER_SECONDS
+        ),
+        replayed=_oauth_error(
+            400, "invalid_request", "this connect flow was already completed; restart the connection"
+        ),
+    )
+    if flow_refusal is not None:
+        return flow_refusal
     response: Final = (
         _denied_flow_response(flow) if decision == "deny" else _approved_flow_response(flow, delivery, team_id, now)
     )
@@ -806,6 +812,27 @@ def _pkce_verifier_matches(code_verifier: str, code_challenge: str) -> bool:
     return hmac.compare_digest(computed, code_challenge.encode("utf-8"))
 
 
+ClaimOutcome = Literal["first", "replayed", "unavailable"]
+
+_CLAIM_UNAVAILABLE_DESCRIPTION: Final = "the single-use record is unavailable right now; try again shortly"
+
+
+def _claim_refusal(outcome: ClaimOutcome, replayed: Response) -> Response | None:
+    """A claim that is not the first caller's is refused, but the two reasons must stay apart on the
+    wire: a replay is the grant's own 4xx, while a shared backend that could not record the claim is
+    a 503 (RFC 7009 section 2.2.1, RFC 6749 section 5.2 ``temporarily_unavailable``), so the client
+    keeps the still-valid token and retries instead of being told it was already used."""
+    match outcome:
+        case "first":
+            return None
+        case "replayed":
+            return replayed
+        case "unavailable":
+            return _oauth_error(503, "temporarily_unavailable", _CLAIM_UNAVAILABLE_DESCRIPTION)
+        case _:
+            assert_never(outcome)
+
+
 class _SingleUseGuard:
     """Atomic single-use claim for a one-time id (an auth-code, connect-flow ``jti``, or refresh-token
     ``jti``) over the injected proxy cache.
@@ -829,9 +856,10 @@ class _SingleUseGuard:
     def __init__(self, cache: DualCache) -> None:
         self._cache = cache
 
-    async def claim(self, key: str, ttl_seconds: int) -> bool:
-        """Atomically claim ``key``. ``True`` iff this caller is the first (increment to 1); ``False``
-        on a replay (>1) or when the claim could not be recorded in the shared backend (fail closed)."""
+    async def claim(self, key: str, ttl_seconds: int) -> ClaimOutcome:
+        """Atomically claim ``key``. ``"first"`` iff this caller is the first (increment to 1),
+        ``"replayed"`` on a replay (>1), and ``"unavailable"`` when the claim could not be recorded in
+        the shared backend, which every caller treats as a refusal (fail closed)."""
         from litellm.proxy.proxy_server import redis_usage_cache  # noqa: PLC0415  # circular import at module load
 
         # Resolve the shared authority HERE rather than trusting the injected cache: callers pass
@@ -850,11 +878,11 @@ class _SingleUseGuard:
                 verbose_logger.warning(
                     "mcp gateway single-use claim: shared cache backend unavailable, failing closed: %s", e
                 )
-                return False
-            return count == 1
+                return "unavailable"
+            return "first" if count == 1 else "replayed"
         # No shared backend configured (single-replica): the in-memory increment is authoritative.
         count = await self._cache.async_increment_cache(key, 1, ttl=ttl_seconds, local_only=True)
-        return count == 1
+        return "first" if count == 1 else "replayed"
 
 
 def _session_token_pair(principal: SessionPrincipal, keys: SessionKeys, now: datetime) -> Response:
@@ -1046,8 +1074,9 @@ class _GrantIssuer:
         failure: Final = await self._reload_user(principal.user_id)
         if failure is not None:
             return _reload_failure_response(failure)
-        if not await self._guard.claim(claim_key, claim_ttl_seconds):
-            return _oauth_error(400, "invalid_grant", replayed)
+        refusal: Final = await self._claim_refusal(claim_key, claim_ttl_seconds, replayed)
+        if refusal is not None:
+            return refusal
         return _session_token_pair(principal, self._keys, self._now)
 
     async def _issue_proxy_credential(
@@ -1060,10 +1089,16 @@ class _GrantIssuer:
         minted: Final = await self._mint_proxy_credential(principal.user_id, principal.team_id)
         if not isinstance(minted, MintedProxyCredential):
             return _mint_failure_response(minted)
-        if not await self._guard.claim(claim_key, claim_ttl_seconds):
-            return _oauth_error(400, "invalid_grant", replayed)
+        refusal: Final = await self._claim_refusal(claim_key, claim_ttl_seconds, replayed)
+        if refusal is not None:
+            return refusal
         return _proxy_credential_response(minted, principal, self._keys, self._now)
 
+    async def _claim_refusal(self, claim_key: str, claim_ttl_seconds: int, replayed: str) -> Response | None:
+        return _claim_refusal(
+            await self._guard.claim(claim_key, claim_ttl_seconds), replayed=_oauth_error(400, "invalid_grant", replayed)
+        )
+
 
 async def _authorization_code_grant(
     request: Request,
@@ -1138,7 +1173,10 @@ async def revoke_refresh_token(token: str, client_id: str, master_key: str | Non
     ``jti`` so neither the holder nor a thief can rotate it again. Access tokens are
     stateless and expire on their own (the proxy-API credential within
     ``CLI_JWT_EXPIRATION_HOURS``), so per RFC 7009 section 2.2 an unrecognized or already
-    dead token still answers 200; only an unknown client is refused."""
+    dead token still answers 200; only an unknown client is refused. A live token whose
+    burn could not be recorded in the shared backend answers 503 (section 2.2.1), so the
+    client knows the token still stands and retries instead of reporting a logout that
+    never happened."""
     if not is_gateway_dcr_client_id(client_id) or open_gateway_dcr_client(client_id) is None:
         return _oauth_error(401, "invalid_client", "unknown or malformed client_id")
     if master_key is None:
@@ -1148,7 +1186,9 @@ async def revoke_refresh_token(token: str, client_id: str, master_key: str | Non
     now: Final = datetime.now(timezone.utc)
     opened: Final = open_session_refresh_bearer(token, keys, now, expected_client_id=client_id)
     if isinstance(opened, SessionRefreshOpened):
-        _ = await _SingleUseGuard(cache).claim(
+        burned: Final = await _SingleUseGuard(cache).claim(
             f"{_USED_REFRESH_CACHE_PREFIX}{opened.jti}", SESSION_REFRESH_TTL_SECONDS + _CLAIM_TTL_BUFFER_SECONDS
         )
+        if burned == "unavailable":
+            return _oauth_error(503, "temporarily_unavailable", _CLAIM_UNAVAILABLE_DESCRIPTION)
     return Response(content="{}", media_type="application/json", headers=TOKEN_NO_CACHE_HEADERS)
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_gateway_dcr_flow.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_gateway_dcr_flow.py
index 6c2b1274aa4..761f823076b 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_gateway_dcr_flow.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_gateway_dcr_flow.py
@@ -560,8 +560,8 @@ async def test_single_use_guard_in_memory_is_single_use_within_process():
     from litellm.proxy._experimental.mcp_server.gateway_dcr_flow import _SingleUseGuard
 
     guard = _SingleUseGuard(DualCache())  # redis_cache is None
-    assert await guard.claim("jti-inmem", 60) is True
-    assert await guard.claim("jti-inmem", 60) is False  # replay of the same id
+    assert await guard.claim("jti-inmem", 60) == "first"
+    assert await guard.claim("jti-inmem", 60) == "replayed"
 
 
 @pytest.mark.asyncio
@@ -579,9 +579,9 @@ async def test_single_use_guard_uses_redis_as_sole_authority_when_configured():
     cache.async_increment_cache = AsyncMock(side_effect=AssertionError("must not fall back to in-memory"))
 
     guard = _SingleUseGuard(cache)
-    assert await guard.claim("jti-redis", 60) is True
+    assert await guard.claim("jti-redis", 60) == "first"
     cache.redis_cache.async_increment = AsyncMock(return_value=2)
-    assert await guard.claim("jti-redis", 60) is False  # Redis says 2 → replay
+    assert await guard.claim("jti-redis", 60) == "replayed"
 
 
 @pytest.mark.asyncio
@@ -599,7 +599,7 @@ async def test_single_use_guard_fails_closed_when_redis_errors():
     cache.async_increment_cache = AsyncMock(return_value=1)  # would fail OPEN if the guard fell back
 
     guard = _SingleUseGuard(cache)
-    assert await guard.claim("jti-fault", 60) is False  # fail closed, not a fallback count of 1
+    assert await guard.claim("jti-fault", 60) == "unavailable"  # fail closed, not a fallback count of 1
 
 
 LOOPBACK_REDIRECT_URI = "http://localhost:3118/callback"
@@ -1531,6 +1531,88 @@ async def test_revoke_burns_the_refresh_token_and_answers_200_for_dead_or_unknow
     assert garbage.status_code == 200
 
 
+def _redis_that(async_increment):
+    from unittest.mock import AsyncMock, MagicMock
+
+    cache = DualCache()
+    cache.redis_cache = MagicMock()
+    cache.redis_cache.async_increment = async_increment
+    cache.async_increment_cache = AsyncMock(side_effect=AssertionError("must not fall back to in-memory"))
+    return cache
+
+
+@pytest.mark.asyncio
+async def test_revoke_answers_503_while_the_shared_record_cannot_be_written_then_burns_the_token():
+    """A revocation whose single-use marker never reached Redis must not report success: the token is
+    still redeemable on every worker, so the client has to hear 503 (RFC 7009 2.2.1) and retry."""
+    from unittest.mock import AsyncMock
+
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    issued = DualCache()
+    payload = json.loads(
+        (await _redeem_native(await _native_code(client_id, cache=issued), client_id, _Minter(), cache=issued)).body
+    )
+
+    redis_down = await revoke_refresh_token(
+        token=payload["refresh_token"],
+        client_id=client_id,
+        master_key=MASTER_KEY,
+        cache=_redis_that(AsyncMock(side_effect=ConnectionError("redis down"))),
+    )
+    assert redis_down.status_code == 503
+    assert json.loads(redis_down.body) == {
+        "error": "temporarily_unavailable",
+        "error_description": "the single-use record is unavailable right now; try again shortly",
+    }
+    assert redis_down.headers["cache-control"] == "no-store"
+
+    redis_back = await revoke_refresh_token(
+        token=payload["refresh_token"],
+        client_id=client_id,
+        master_key=MASTER_KEY,
+        cache=_redis_that(AsyncMock(return_value=1)),
+    )
+    assert redis_back.status_code == 200
+    assert json.loads(redis_back.body) == {}
+
+    already_burned = await revoke_refresh_token(
+        token=payload["refresh_token"],
+        client_id=client_id,
+        master_key=MASTER_KEY,
+        cache=_redis_that(AsyncMock(return_value=2)),
+    )
+    assert already_burned.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_refresh_answers_503_without_burning_the_token_while_redis_is_down():
+    """Fail closed, but say why: a refresh the shared backend could not record is refused with 503
+    rather than ``invalid_grant``, so the CLI keeps the key it has and retries instead of telling the
+    user the token was already used and sending them back through the browser."""
+    from unittest.mock import AsyncMock
+
+    client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
+    issued = DualCache()
+    payload = json.loads(
+        (await _redeem_native(await _native_code(client_id, cache=issued), client_id, _Minter(), cache=issued)).body
+    )
+
+    redis_down = await _refresh_native(
+        payload["refresh_token"], client_id, _Minter(), _redis_that(AsyncMock(side_effect=ConnectionError("redis down")))
+    )
+    assert redis_down.status_code == 503
+    assert json.loads(redis_down.body)["error"] == "temporarily_unavailable"
+    assert "refresh_token" not in json.loads(redis_down.body)
+
+    redis_back = await _refresh_native(payload["refresh_token"], client_id, _Minter(), _redis_that(AsyncMock(return_value=1)))
+    assert redis_back.status_code == 200
+    assert json.loads(redis_back.body)["refresh_token"] != payload["refresh_token"]
+
+    replayed = await _refresh_native(payload["refresh_token"], client_id, _Minter(), _redis_that(AsyncMock(return_value=2)))
+    assert replayed.status_code == 400
+    assert json.loads(replayed.body)["error"] == "invalid_grant"
+
+
 @pytest.mark.asyncio
 async def test_revoke_from_another_client_leaves_the_token_usable():
     client_id = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]

From 64e7ab1beb83976fbb0bbdd2bc0774b3d11d453d Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 20 Aug 2026 08:16:30 -0700
Subject: [PATCH 28/35] fix(cli): keep the login record when the proxy cannot
 record a logout's revocation

A 503 from POST /revoke means the proxy could not write the single-use record, so clearing the local record left a live refresh token nobody could revoke and a hint to retry with nothing left to retry. lite logout now keeps the record, exits 1, and asks to be run again shortly. A refused or unreachable revocation still clears the record and warns as before, and a re-login that replaces a record keeps its existing warning because the new record already stands
---
 .../mcp_server/discoverable_endpoints.py      |  5 +--
 litellm/proxy/client/cli/commands/auth.py     | 18 +++++++---
 .../proxy/client/cli/commands/pkce_login.py   | 15 ++++++--
 .../proxy/client/cli/test_auth_commands.py    | 36 ++++++++++++++++---
 .../proxy/client/cli/test_pkce_login.py       | 15 ++++++++
 5 files changed, 76 insertions(+), 13 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py b/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
index f9c5db76fa0..2994f98f309 100644
--- a/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
+++ b/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
@@ -1842,8 +1842,9 @@ async def authorize_complete(
 
 @router.post("/revoke")
 async def revoke_endpoint(request: Request, token: str = Form(...), client_id: str = Form(...)) -> Response:
-    """RFC 7009 revocation for the gateway's refresh tokens (``lite logout``). Always 200
-    for a known client, whatever the token's state; access tokens expire on their own."""
+    """RFC 7009 revocation for the gateway's refresh tokens (``lite logout``): 200 for a known
+    client whatever the token's state, 503 when the shared single-use record cannot be written;
+    access tokens expire on their own."""
     from litellm.proxy.proxy_server import (  # noqa: PLC0415  # circular import at module load
         master_key,
         user_api_key_cache,
diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py
index 4eb23a547b6..31583dec978 100644
--- a/litellm/proxy/client/cli/commands/auth.py
+++ b/litellm/proxy/client/cli/commands/auth.py
@@ -11,7 +11,7 @@ import click
 import requests
 from rich.console import Console
 from rich.table import Table
-from typing_extensions import NotRequired, ReadOnly, TypedDict
+from typing_extensions import NotRequired, ReadOnly, TypedDict, assert_never
 
 from litellm.constants import CLI_JWT_EXPIRATION_HOURS
 from litellm.litellm_core_utils.cli_token_utils import is_cli_token_fresh
@@ -25,6 +25,7 @@ from .claude_settings import (
 from .pkce_login import (
     Http,
     PkceFailure,
+    RevocationUnavailable,
     fresh_api_key,
     pkce_token_record,
     revoke_stored_credential,
@@ -805,9 +806,18 @@ def logout():
     """Logout and clear stored authentication"""
     token_data: Final = load_token()
     revocation: Final = revoke_stored_credential(token_data, requests.Session()) if token_data is not None else None
-    clear_token()
-    if revocation is not None:
-        click.echo(f"Could not revoke the refresh token on the proxy ({revocation.reason}); it expires on its own.")
+    match revocation:
+        case RevocationUnavailable(reason=reason):
+            raise click.ClickException(
+                f"The proxy could not record the revocation ({reason}). Nothing was cleared; run `lite logout` again shortly."
+            )
+        case PkceFailure(reason=reason):
+            clear_token()
+            click.echo(f"Could not revoke the refresh token on the proxy ({reason}); it expires on its own.")
+        case None:
+            clear_token()
+        case _:
+            assert_never(revocation)
     click.echo("Logged out successfully. Authentication token cleared.")
 
 
diff --git a/litellm/proxy/client/cli/commands/pkce_login.py b/litellm/proxy/client/cli/commands/pkce_login.py
index a0db1ba2db7..93f5cfea21b 100644
--- a/litellm/proxy/client/cli/commands/pkce_login.py
+++ b/litellm/proxy/client/cli/commands/pkce_login.py
@@ -69,6 +69,11 @@ class PkceFailure:
     reason: str
 
 
+@dataclass(frozen=True, slots=True)
+class RevocationUnavailable:
+    reason: str
+
+
 @dataclass(frozen=True, slots=True)
 class PkceCredential:
     access_token: str
@@ -396,7 +401,9 @@ def _token_request(
     )
 
 
-def revoke_credential(revocation_endpoint: str, client_id: str, refresh_token: str, http: Http) -> PkceFailure | None:
+def revoke_credential(
+    revocation_endpoint: str, client_id: str, refresh_token: str, http: Http
+) -> PkceFailure | RevocationUnavailable | None:
     try:
         response: Final = http.post(
             revocation_endpoint,
@@ -409,6 +416,8 @@ def revoke_credential(revocation_endpoint: str, client_id: str, refresh_token: s
     redirected: Final = _refused_redirect("revocation request", response)
     if redirected is not None:
         return redirected
+    if response.status_code == 503:
+        return RevocationUnavailable(f"revocation failed with 503: {_error_detail(response)}")
     if response.status_code != 200:
         return PkceFailure(f"revocation failed with {response.status_code}: {_error_detail(response)}")
     return None
@@ -554,7 +563,9 @@ def _refresh_inputs(token_data: Mapping[str, object]) -> tuple[str, str, str, st
     return str(token_endpoint), str(revocation_endpoint), str(resource), str(client_id), str(refresh_token)
 
 
-def revoke_stored_credential(token_data: Mapping[str, object], http: Http) -> PkceFailure | None:
+def revoke_stored_credential(
+    token_data: Mapping[str, object], http: Http
+) -> PkceFailure | RevocationUnavailable | None:
     refresh_inputs: Final = _refresh_inputs(token_data)
     if refresh_inputs is None:
         return None
diff --git a/tests/test_litellm/proxy/client/cli/test_auth_commands.py b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
index f6123b5c690..c494cf8b45b 100644
--- a/tests/test_litellm/proxy/client/cli/test_auth_commands.py
+++ b/tests/test_litellm/proxy/client/cli/test_auth_commands.py
@@ -1429,24 +1429,50 @@ class TestPkceLogoutCommand:
             )
         ]
 
-    def test_logout_still_clears_when_revocation_fails(self):
-        class _FailingSession(_FakeSession):
+    def test_logout_still_clears_when_the_proxy_refuses_the_revocation(self):
+        class _RefusingSession(_FakeSession):
             def __init__(self):
                 super().__init__()
-                self.response = _FakeHttpResponse(503, {"error": "temporarily_unavailable"})
+                self.response = _FakeHttpResponse(401, {"error": "invalid_client"})
 
         with (
             patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=_pkce_record()),
             patch("litellm.proxy.client.cli.commands.auth.clear_token") as clear,
-            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _FailingSession),
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _RefusingSession),
         ):
             result = self.runner.invoke(logout)
 
         assert result.exit_code == 0
-        assert "Could not revoke the refresh token on the proxy (revocation failed with 503" in result.output
+        assert (
+            "Could not revoke the refresh token on the proxy (revocation failed with 401: invalid_client); "
+            "it expires on its own." in result.output
+        )
         assert "Logged out successfully" in result.output
         clear.assert_called_once()
 
+    def test_logout_keeps_the_record_when_the_proxy_cannot_record_the_revocation(self):
+        class _UnavailableSession(_FakeSession):
+            def __init__(self):
+                super().__init__()
+                self.response = _FakeHttpResponse(
+                    503, {"error": "temporarily_unavailable", "error_description": "the record is unavailable"}
+                )
+
+        with (
+            patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=_pkce_record()),
+            patch("litellm.proxy.client.cli.commands.auth.clear_token") as clear,
+            patch("litellm.proxy.client.cli.commands.auth.requests.Session", _UnavailableSession),
+        ):
+            result = self.runner.invoke(logout)
+
+        assert result.exit_code == 1
+        assert (
+            "Error: The proxy could not record the revocation (revocation failed with 503: the record is unavailable). "
+            "Nothing was cleared; run `lite logout` again shortly." in result.output
+        )
+        assert "Logged out successfully" not in result.output
+        clear.assert_not_called()
+
     def test_logout_of_a_classic_token_makes_no_request(self):
         with (
             patch("litellm.proxy.client.cli.commands.auth.load_token", return_value={"key": "sk-classic"}),
diff --git a/tests/test_litellm/proxy/client/cli/test_pkce_login.py b/tests/test_litellm/proxy/client/cli/test_pkce_login.py
index 712c7e83236..70f481d5cfa 100644
--- a/tests/test_litellm/proxy/client/cli/test_pkce_login.py
+++ b/tests/test_litellm/proxy/client/cli/test_pkce_login.py
@@ -22,6 +22,7 @@ from litellm.proxy.client.cli.commands.pkce_login import (
     LoopbackServer,
     PkceCredential,
     PkceFailure,
+    RevocationUnavailable,
     _error_detail,
     authorize_url,
     discover_cli_auth,
@@ -408,6 +409,20 @@ def test_revoke_failures_name_the_cause(response, expected):
     assert expected in result.reason
 
 
+def test_revoke_reports_a_503_as_unavailable_so_the_caller_can_retry():
+    response = _FakeResponse(
+        503,
+        {
+            "error": "temporarily_unavailable",
+            "error_description": "the single-use record is unavailable right now; try again shortly",
+        },
+    )
+    result = revoke_credential(f"{BASE}/revoke", "llm_dcrc_abc", "t", _FakeHttp({("POST", f"{BASE}/revoke"): response}))
+    assert result == RevocationUnavailable(
+        "revocation failed with 503: the single-use record is unavailable right now; try again shortly"
+    )
+
+
 @pytest.mark.parametrize("status", [302, 307, 308])
 def test_posts_to_the_proxy_never_follow_a_redirect(status):
     elsewhere = "https://evil.example.net/oauth"

From 68deda3da754430fcae3f96a810862ae5361ddfc Mon Sep 17 00:00:00 2001
From: yuneng-jiang <yuneng@berri.ai>
Date: Thu, 20 Aug 2026 10:07:02 -0700
Subject: [PATCH 29/35] refactor(ci): fold the nine thin unit-shard callers
 into one matrix (#37590)

Nine workflow files existed only to make a single call to _test-unit-base.yml
with a different test-path. Adding a shard meant adding a file; changing
anything shared meant editing nine. One matrix caller replaces them, so a shard
is now one entry.

Check names are unchanged, which is the whole constraint. A reusable-workflow
job reports as "<job name> / <inner job name>", so setting `name` to the shard id
alone reproduces today's context strings exactly: the eleven the matrix produces
are eleven of the twenty-three "/ Run tests" contexts the branch ruleset
requires, matched string for string. No ruleset edit is needed and none should
be made for this.

Every matrix entry states its timeouts even where they equal the base defaults.
An absent matrix key renders as an empty string rather than falling back, and an
empty string is not a number, so a partially-specified entry would fail the call.

tests/proxy_unit_tests keeps test-unit-proxy-db.yml. It is already a matrix and
its shard-coverage guard reads that file by name, so folding it in belongs with
generalising that guard into assert_ci_coverage.py rather than here. Its twelve
shards are the remaining required contexts.

test-unit-documentation.yml stays too: it does not call the base workflow.
---
 .github/workflows/test-unit-core-utils.yml    |  31 ---
 .../test-unit-enterprise-routing.yml          |  35 ---
 .github/workflows/test-unit-integrations.yml  |  31 ---
 .github/workflows/test-unit-llm-providers.yml |  47 ----
 .github/workflows/test-unit-misc.yml          |  53 -----
 .github/workflows/test-unit-proxy-auth.yml    |  31 ---
 .../workflows/test-unit-proxy-endpoints.yml   |  81 -------
 .github/workflows/test-unit-proxy-infra.yml   |  42 ----
 .../test-unit-responses-caching-types.yml     |  31 ---
 .github/workflows/test-unit.yml               | 219 ++++++++++++++++++
 10 files changed, 219 insertions(+), 382 deletions(-)
 delete mode 100644 .github/workflows/test-unit-core-utils.yml
 delete mode 100644 .github/workflows/test-unit-enterprise-routing.yml
 delete mode 100644 .github/workflows/test-unit-integrations.yml
 delete mode 100644 .github/workflows/test-unit-llm-providers.yml
 delete mode 100644 .github/workflows/test-unit-misc.yml
 delete mode 100644 .github/workflows/test-unit-proxy-auth.yml
 delete mode 100644 .github/workflows/test-unit-proxy-endpoints.yml
 delete mode 100644 .github/workflows/test-unit-proxy-infra.yml
 delete mode 100644 .github/workflows/test-unit-responses-caching-types.yml
 create mode 100644 .github/workflows/test-unit.yml

diff --git a/.github/workflows/test-unit-core-utils.yml b/.github/workflows/test-unit-core-utils.yml
deleted file mode 100644
index a01f09559c6..00000000000
--- a/.github/workflows/test-unit-core-utils.yml
+++ /dev/null
@@ -1,31 +0,0 @@
-name: "Unit Tests: Core Utilities"
-
-on:
-  pull_request:
-    branches:
-      - main
-      - litellm_internal_staging
-      - litellm_oss_staging
-      - "litellm_**"
-  push:
-    branches:
-      - main
-      - litellm_internal_staging
-
-permissions:
-  contents: read
-  id-token: write
-  pull-requests: write
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  core-utils:
-    uses: ./.github/workflows/_test-unit-base.yml
-    with:
-      test-path: "tests/test_litellm/litellm_core_utils"
-      workers: 2
-      reruns: 1
-      artifact-name: core-utils
diff --git a/.github/workflows/test-unit-enterprise-routing.yml b/.github/workflows/test-unit-enterprise-routing.yml
deleted file mode 100644
index a64f00f4744..00000000000
--- a/.github/workflows/test-unit-enterprise-routing.yml
+++ /dev/null
@@ -1,35 +0,0 @@
-name: "Unit Tests: Enterprise, Google GenAI & Routing"
-
-on:
-  pull_request:
-    branches:
-      - main
-      - litellm_internal_staging
-      - litellm_oss_staging
-      - "litellm_**"
-  push:
-    branches:
-      - main
-      - litellm_internal_staging
-
-permissions:
-  contents: read
-  id-token: write
-  pull-requests: write
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  enterprise-routing:
-    uses: ./.github/workflows/_test-unit-base.yml
-    with:
-      test-path: >-
-        tests/test_litellm/enterprise
-        tests/test_litellm/google_genai
-        tests/test_litellm/router_utils
-        tests/test_litellm/router_strategy
-      workers: 2
-      reruns: 2
-      artifact-name: enterprise-routing
diff --git a/.github/workflows/test-unit-integrations.yml b/.github/workflows/test-unit-integrations.yml
deleted file mode 100644
index 39752cf8e5d..00000000000
--- a/.github/workflows/test-unit-integrations.yml
+++ /dev/null
@@ -1,31 +0,0 @@
-name: "Unit Tests: Integrations (Callbacks & Logging)"
-
-on:
-  pull_request:
-    branches:
-      - main
-      - litellm_internal_staging
-      - litellm_oss_staging
-      - "litellm_**"
-  push:
-    branches:
-      - main
-      - litellm_internal_staging
-
-permissions:
-  contents: read
-  id-token: write
-  pull-requests: write
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  integrations:
-    uses: ./.github/workflows/_test-unit-base.yml
-    with:
-      test-path: "tests/test_litellm/integrations"
-      workers: 2
-      reruns: 3
-      artifact-name: integrations
diff --git a/.github/workflows/test-unit-llm-providers.yml b/.github/workflows/test-unit-llm-providers.yml
deleted file mode 100644
index 4d1c921f723..00000000000
--- a/.github/workflows/test-unit-llm-providers.yml
+++ /dev/null
@@ -1,47 +0,0 @@
-name: "Unit Tests: LLM Provider Transformations"
-
-on:
-  pull_request:
-    branches:
-      - main
-      - litellm_internal_staging
-      - litellm_oss_staging
-      - "litellm_**"
-  push:
-    branches:
-      - main
-      - litellm_internal_staging
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  vertex-ai:
-    name: Vertex AI
-    permissions:
-      contents: read
-      id-token: write
-      pull-requests: write
-    uses: ./.github/workflows/_test-unit-base.yml
-    with:
-      test-path: "tests/test_litellm/llms/vertex_ai"
-      workers: 1
-      reruns: 2
-      artifact-name: llm-vertex-ai
-
-  other-providers:
-    name: All Other Providers
-    permissions:
-      contents: read
-      id-token: write
-      pull-requests: write
-    uses: ./.github/workflows/_test-unit-base.yml
-    with:
-      test-path: "tests/test_litellm/llms --ignore=tests/test_litellm/llms/vertex_ai"
-      workers: 2
-      reruns: 2
-      artifact-name: llm-other-providers
diff --git a/.github/workflows/test-unit-misc.yml b/.github/workflows/test-unit-misc.yml
deleted file mode 100644
index 123a31e23f7..00000000000
--- a/.github/workflows/test-unit-misc.yml
+++ /dev/null
@@ -1,53 +0,0 @@
-name: "Unit Tests: MCP, Secrets, Containers & Misc"
-
-on:
-  pull_request:
-    branches:
-      - main
-      - litellm_internal_staging
-      - litellm_oss_staging
-      - "litellm_**"
-  push:
-    branches:
-      - main
-      - litellm_internal_staging
-
-permissions:
-  contents: read
-  id-token: write
-  pull-requests: write
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  misc:
-    uses: ./.github/workflows/_test-unit-base.yml
-    with:
-      test-path: >-
-        tests/test_litellm/batches
-        tests/test_litellm/secret_managers
-        tests/test_litellm/a2a_protocol
-        tests/test_litellm/anthropic_interface
-        tests/test_litellm/completion_extras
-        tests/test_litellm/compression
-        tests/test_litellm/containers
-        tests/test_litellm/experimental_mcp_client
-        tests/test_litellm/models
-        tests/test_litellm/repositories
-        tests/test_litellm/images
-        tests/test_litellm/interactions
-        tests/test_litellm/ocr
-        tests/test_litellm/passthrough
-        tests/test_litellm/rag
-        tests/test_litellm/realtime_api
-        tests/test_litellm/rerank_api
-        tests/test_litellm/sandbox
-        tests/test_litellm/test_router
-        tests/test_litellm/vector_stores
-        tests/test_litellm/videos
-        tests/test_litellm/test_*.py
-      workers: 2
-      reruns: 2
-      artifact-name: misc
diff --git a/.github/workflows/test-unit-proxy-auth.yml b/.github/workflows/test-unit-proxy-auth.yml
deleted file mode 100644
index c27fe16d611..00000000000
--- a/.github/workflows/test-unit-proxy-auth.yml
+++ /dev/null
@@ -1,31 +0,0 @@
-name: "Unit Tests: Proxy Auth & Key Management"
-
-on:
-  pull_request:
-    branches:
-      - main
-      - litellm_internal_staging
-      - litellm_oss_staging
-      - "litellm_**"
-  push:
-    branches:
-      - main
-      - litellm_internal_staging
-
-permissions:
-  contents: read
-  id-token: write
-  pull-requests: write
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  proxy-auth:
-    uses: ./.github/workflows/_test-unit-base.yml
-    with:
-      test-path: "tests/test_litellm/proxy/auth tests/test_litellm/proxy/hooks tests/test_litellm/proxy/policy_engine tests/test_litellm/proxy/client"
-      workers: 2
-      reruns: 2
-      artifact-name: proxy-auth
diff --git a/.github/workflows/test-unit-proxy-endpoints.yml b/.github/workflows/test-unit-proxy-endpoints.yml
deleted file mode 100644
index 3d1d0fcd6c3..00000000000
--- a/.github/workflows/test-unit-proxy-endpoints.yml
+++ /dev/null
@@ -1,81 +0,0 @@
-name: "Unit Tests: Proxy API Endpoints"
-
-on:
-  pull_request:
-    branches:
-      - main
-      - litellm_internal_staging
-      - litellm_oss_staging
-      - "litellm_**"
-  push:
-    branches:
-      - main
-      - litellm_internal_staging
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  proxy-endpoints:
-    permissions:
-      contents: read
-      id-token: write
-      pull-requests: write
-    uses: ./.github/workflows/_test-unit-base.yml
-    with:
-      test-path: >-
-        tests/test_litellm/proxy/analytics_endpoints
-        tests/test_litellm/proxy/management_endpoints
-        tests/test_litellm/proxy/memory
-        tests/test_litellm/proxy/guardrails
-        tests/test_litellm/proxy/management_helpers
-        tests/test_litellm/proxy/anthropic_endpoints
-        tests/test_litellm/proxy/google_endpoints
-        tests/test_litellm/proxy/openai_files_endpoint
-        tests/test_litellm/proxy/batches_endpoints
-        tests/test_litellm/proxy/fine_tuning_endpoints
-        tests/test_litellm/proxy/vector_store_files_endpoints
-        tests/test_litellm/proxy/video_endpoints
-        tests/test_litellm/proxy/response_api_endpoints
-        tests/test_litellm/proxy/image_endpoints
-        tests/test_litellm/proxy/ocr_endpoints
-        tests/test_litellm/proxy/vector_store_endpoints
-        tests/test_litellm/proxy/agent_endpoints
-        tests/test_litellm/proxy/a2a
-        tests/test_litellm/proxy/credential_endpoints
-        tests/test_litellm/proxy/discovery_endpoints
-        tests/test_litellm/proxy/health_endpoints
-        tests/test_litellm/proxy/shutdown
-        tests/test_litellm/proxy/public_endpoints
-        tests/test_litellm/proxy/prompts
-        tests/test_litellm/proxy/rag_endpoints
-        tests/test_litellm/proxy/realtime_endpoints
-        tests/test_litellm/proxy/ui_crud_endpoints
-        tests/test_litellm/proxy/config_resolvers
-        tests/test_litellm/proxy/utils
-      workers: 2
-      reruns: 2
-      artifact-name: proxy-endpoints
-
-  # Behavior-pinning tests for litellm/proxy/proxy_server.py. Owns its
-  # own job (not a path on the proxy-endpoints job above) so its budget
-  # is independent and its coverage artifact is uploaded separately.
-  # See: https://www.notion.so/36c43b8acdab81ee845fd5365128a2fc
-  proxy-server:
-    permissions:
-      contents: read
-      id-token: write
-      pull-requests: write
-    uses: ./.github/workflows/_test-unit-base.yml
-    with:
-      test-path: tests/test_litellm/proxy/proxy_server
-      workers: 4
-      reruns: 2
-      timeout-minutes: 60
-      job-timeout-minutes: 95
-      artifact-name: proxy-server
diff --git a/.github/workflows/test-unit-proxy-infra.yml b/.github/workflows/test-unit-proxy-infra.yml
deleted file mode 100644
index 83d95463cdf..00000000000
--- a/.github/workflows/test-unit-proxy-infra.yml
+++ /dev/null
@@ -1,42 +0,0 @@
-name: "Unit Tests: Proxy Infrastructure"
-
-on:
-  pull_request:
-    branches:
-      - main
-      - litellm_internal_staging
-      - litellm_oss_staging
-      - "litellm_**"
-  push:
-    branches:
-      - main
-      - litellm_internal_staging
-
-permissions:
-  contents: read
-  id-token: write
-  pull-requests: write
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  proxy-infra:
-    uses: ./.github/workflows/_test-unit-base.yml
-    with:
-      test-path: >-
-        tests/test_litellm/proxy/db
-        tests/test_litellm/proxy/middleware
-        tests/test_litellm/proxy/spend_tracking
-        tests/test_litellm/proxy/pass_through_endpoints
-        tests/test_litellm/proxy/_experimental
-        tests/test_litellm/proxy/experimental
-        tests/test_litellm/proxy/common_utils
-        tests/test_litellm/proxy/enterprise_billing
-        tests/test_litellm/proxy/types_utils
-        tests/test_litellm/proxy/logging_endpoints
-        tests/test_litellm/proxy/test_*.py
-      workers: 2
-      reruns: 2
-      artifact-name: proxy-infra
diff --git a/.github/workflows/test-unit-responses-caching-types.yml b/.github/workflows/test-unit-responses-caching-types.yml
deleted file mode 100644
index 5b336452069..00000000000
--- a/.github/workflows/test-unit-responses-caching-types.yml
+++ /dev/null
@@ -1,31 +0,0 @@
-name: "Unit Tests: Responses, Caching & Types"
-
-on:
-  pull_request:
-    branches:
-      - main
-      - litellm_internal_staging
-      - litellm_oss_staging
-      - "litellm_**"
-  push:
-    branches:
-      - main
-      - litellm_internal_staging
-
-permissions:
-  contents: read
-  id-token: write
-  pull-requests: write
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  responses-caching-types:
-    uses: ./.github/workflows/_test-unit-base.yml
-    with:
-      test-path: "tests/test_litellm/responses tests/test_litellm/caching tests/test_litellm/types"
-      workers: 2
-      reruns: 2
-      artifact-name: responses-caching-types
diff --git a/.github/workflows/test-unit.yml b/.github/workflows/test-unit.yml
new file mode 100644
index 00000000000..fbba9969c28
--- /dev/null
+++ b/.github/workflows/test-unit.yml
@@ -0,0 +1,219 @@
+name: "Unit Tests"
+
+on:
+  pull_request:
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_staging
+      - "litellm_**"
+  push:
+    branches:
+      - main
+      - litellm_internal_staging
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+# One caller for every tests/test_litellm shard, replacing the nine thin workflow
+# files that each wrapped a single call to _test-unit-base.yml. Adding a shard is
+# now one matrix entry rather than a new file.
+#
+# `name` is the shard id and nothing else, so each check reports as
+# "<shard> / Run tests" exactly as it did when the shard had its own file. Those
+# strings are the branch ruleset's required contexts, so they are load-bearing:
+# renaming an entry renames a required check and the ruleset stops matching it.
+#
+# Every entry states its timeouts even when they equal the base workflow's
+# defaults. An absent matrix key renders as an empty string, which is not a
+# number, so a partially-specified entry would fail the call rather than fall
+# back to the default.
+#
+# tests/proxy_unit_tests keeps its own caller (test-unit-proxy-db.yml): it is
+# already a matrix and carries a shard-coverage guard that reads that file by
+# name. Folding it in here is a follow-up, together with generalising that guard
+# into assert_ci_coverage.py.
+jobs:
+  unit:
+    name: ${{ matrix.shard }}
+    permissions:
+      contents: read
+      id-token: write
+      pull-requests: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - shard: core-utils
+            artifact-name: core-utils
+            test-path: "tests/test_litellm/litellm_core_utils"
+            workers: 2
+            reruns: 1
+            timeout-minutes: 20
+            job-timeout-minutes: 55
+
+          - shard: enterprise-routing
+            artifact-name: enterprise-routing
+            test-path: >-
+              tests/test_litellm/enterprise
+              tests/test_litellm/google_genai
+              tests/test_litellm/router_utils
+              tests/test_litellm/router_strategy
+            workers: 2
+            reruns: 2
+            timeout-minutes: 20
+            job-timeout-minutes: 55
+
+          - shard: integrations
+            artifact-name: integrations
+            test-path: "tests/test_litellm/integrations"
+            workers: 2
+            reruns: 3
+            timeout-minutes: 20
+            job-timeout-minutes: 55
+
+          - shard: Vertex AI
+            artifact-name: llm-vertex-ai
+            test-path: "tests/test_litellm/llms/vertex_ai"
+            workers: 1
+            reruns: 2
+            timeout-minutes: 20
+            job-timeout-minutes: 55
+
+          - shard: All Other Providers
+            artifact-name: llm-other-providers
+            test-path: "tests/test_litellm/llms --ignore=tests/test_litellm/llms/vertex_ai"
+            workers: 2
+            reruns: 2
+            timeout-minutes: 20
+            job-timeout-minutes: 55
+
+          - shard: misc
+            artifact-name: misc
+            test-path: >-
+              tests/test_litellm/batches
+              tests/test_litellm/secret_managers
+              tests/test_litellm/a2a_protocol
+              tests/test_litellm/anthropic_interface
+              tests/test_litellm/completion_extras
+              tests/test_litellm/compression
+              tests/test_litellm/containers
+              tests/test_litellm/experimental_mcp_client
+              tests/test_litellm/models
+              tests/test_litellm/repositories
+              tests/test_litellm/images
+              tests/test_litellm/interactions
+              tests/test_litellm/ocr
+              tests/test_litellm/passthrough
+              tests/test_litellm/rag
+              tests/test_litellm/realtime_api
+              tests/test_litellm/rerank_api
+              tests/test_litellm/sandbox
+              tests/test_litellm/test_router
+              tests/test_litellm/vector_stores
+              tests/test_litellm/videos
+              tests/test_litellm/test_*.py
+            workers: 2
+            reruns: 2
+            timeout-minutes: 20
+            job-timeout-minutes: 55
+
+          - shard: proxy-auth
+            artifact-name: proxy-auth
+            test-path: >-
+              tests/test_litellm/proxy/auth
+              tests/test_litellm/proxy/hooks
+              tests/test_litellm/proxy/policy_engine
+              tests/test_litellm/proxy/client
+            workers: 2
+            reruns: 2
+            timeout-minutes: 20
+            job-timeout-minutes: 55
+
+          - shard: proxy-endpoints
+            artifact-name: proxy-endpoints
+            test-path: >-
+              tests/test_litellm/proxy/analytics_endpoints
+              tests/test_litellm/proxy/management_endpoints
+              tests/test_litellm/proxy/memory
+              tests/test_litellm/proxy/guardrails
+              tests/test_litellm/proxy/management_helpers
+              tests/test_litellm/proxy/anthropic_endpoints
+              tests/test_litellm/proxy/google_endpoints
+              tests/test_litellm/proxy/openai_files_endpoint
+              tests/test_litellm/proxy/batches_endpoints
+              tests/test_litellm/proxy/fine_tuning_endpoints
+              tests/test_litellm/proxy/vector_store_files_endpoints
+              tests/test_litellm/proxy/video_endpoints
+              tests/test_litellm/proxy/response_api_endpoints
+              tests/test_litellm/proxy/image_endpoints
+              tests/test_litellm/proxy/ocr_endpoints
+              tests/test_litellm/proxy/vector_store_endpoints
+              tests/test_litellm/proxy/agent_endpoints
+              tests/test_litellm/proxy/a2a
+              tests/test_litellm/proxy/credential_endpoints
+              tests/test_litellm/proxy/discovery_endpoints
+              tests/test_litellm/proxy/health_endpoints
+              tests/test_litellm/proxy/shutdown
+              tests/test_litellm/proxy/public_endpoints
+              tests/test_litellm/proxy/prompts
+              tests/test_litellm/proxy/rag_endpoints
+              tests/test_litellm/proxy/realtime_endpoints
+              tests/test_litellm/proxy/ui_crud_endpoints
+              tests/test_litellm/proxy/config_resolvers
+              tests/test_litellm/proxy/utils
+            workers: 2
+            reruns: 2
+            timeout-minutes: 20
+            job-timeout-minutes: 55
+
+          - shard: proxy-server
+            artifact-name: proxy-server
+            test-path: "tests/test_litellm/proxy/proxy_server"
+            workers: 4
+            reruns: 2
+            timeout-minutes: 60
+            job-timeout-minutes: 95
+
+          - shard: proxy-infra
+            artifact-name: proxy-infra
+            test-path: >-
+              tests/test_litellm/proxy/db
+              tests/test_litellm/proxy/middleware
+              tests/test_litellm/proxy/spend_tracking
+              tests/test_litellm/proxy/pass_through_endpoints
+              tests/test_litellm/proxy/_experimental
+              tests/test_litellm/proxy/experimental
+              tests/test_litellm/proxy/common_utils
+              tests/test_litellm/proxy/enterprise_billing
+              tests/test_litellm/proxy/types_utils
+              tests/test_litellm/proxy/logging_endpoints
+              tests/test_litellm/proxy/test_*.py
+            workers: 2
+            reruns: 2
+            timeout-minutes: 20
+            job-timeout-minutes: 55
+
+          - shard: responses-caching-types
+            artifact-name: responses-caching-types
+            test-path: >-
+              tests/test_litellm/responses
+              tests/test_litellm/caching
+              tests/test_litellm/types
+            workers: 2
+            reruns: 2
+            timeout-minutes: 20
+            job-timeout-minutes: 55
+    uses: ./.github/workflows/_test-unit-base.yml
+    with:
+      test-path: ${{ matrix.test-path }}
+      workers: ${{ matrix.workers }}
+      reruns: ${{ matrix.reruns }}
+      timeout-minutes: ${{ matrix.timeout-minutes }}
+      job-timeout-minutes: ${{ matrix.job-timeout-minutes }}
+      artifact-name: ${{ matrix.artifact-name }}

From 5b1a9563d60670e7044497e4be483dfdf2a2fc8b Mon Sep 17 00:00:00 2001
From: yuneng-jiang <yuneng@berri.ai>
Date: Thu, 20 Aug 2026 10:07:14 -0700
Subject: [PATCH 30/35] chore(ci): close the test-census blind spots and move
 scripts out of workflows/ (#37586)

The agent job's CircleCI glob collected `tests/agent_tests/**/test_*.py` and then
piped it through `grep -v` to drop `local_only_agent_tests/`. `assert_ci_coverage.py`
reads the glob but not the pipeline, so those two files looked covered and were
invisible to the census. The glob now excludes them structurally and they carry an
allowlist entry instead, which is a decision on the record rather than a hidden
filter. The collected file set is unchanged: `tests/agent_tests/` holds exactly one
CI-runnable test at the top level.

`tests/scim_tests/` held a single JSON fixture and no tests, referenced from nowhere.

`.github/workflows/` is for workflows. Both stray scripts move to `.github/scripts/`
with their callers updated: the price-file updater is invoked by
`auto_update_price_and_context_window.yml`, and the translation-report runner by
`make test-llm-translation`. The audit listed the latter as orphaned, but Makefile
line 317 still runs it, so it moves rather than being deleted.

The rollout heads-up workflow was a deliberate one-shot for the agent-shin rollout.
That rollout is done, the triage and auto-close workflows have been running daily
since June, so the pre-flip warning window is long past. Its script and dedicated
test go with it, and the sibling workflow-invariant test drops its entry.
---
 .circleci/config.yml                          |   2 +-
 .github/ci-coverage-allowlist.yml             |   8 +
 ...to_update_price_and_context_window_file.py |   0
 .../run_llm_translation_tests.py              |   0
 .github/scripts/triage_rollout_heads_up.py    | 557 -------------
 .../auto_update_price_and_context_window.yml  |   2 +-
 .github/workflows/triage_rollout_heads_up.yml |  92 ---
 Makefile                                      |   2 +-
 tests/scim_tests/scim_e2e_test.json           | 750 ------------------
 .../test_github_triage_workflows.py           |  44 -
 .../test_triage_rollout_heads_up.py           | 612 --------------
 11 files changed, 11 insertions(+), 2058 deletions(-)
 rename .github/{workflows => scripts}/auto_update_price_and_context_window_file.py (100%)
 rename .github/{workflows => scripts}/run_llm_translation_tests.py (100%)
 delete mode 100644 .github/scripts/triage_rollout_heads_up.py
 delete mode 100644 .github/workflows/triage_rollout_heads_up.yml
 delete mode 100644 tests/scim_tests/scim_e2e_test.json
 delete mode 100644 tests/test_litellm/test_triage_rollout_heads_up.py

diff --git a/.circleci/config.yml b/.circleci/config.yml
index e8a8483781b..5e77729df29 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -1025,7 +1025,7 @@ jobs:
           name: Run tests
           command: |
             mkdir -p test-results
-            TEST_FILES=$(circleci tests glob "tests/agent_tests/**/test_*.py" | grep -v "^tests/agent_tests/local_only_agent_tests/")
+            TEST_FILES=$(circleci tests glob "tests/agent_tests/test_*.py")
             echo "$TEST_FILES" | circleci tests run \
               --verbose \
               --command="tr ' ' '\\n' | awk '/\\.py/ {print; next} {sub(/\\.[A-Z][^.]*$/, \"\"); gsub(/\\./, \"/\"); print \$0 \".py\"}' | xargs uv run --no-sync python -m pytest \
diff --git a/.github/ci-coverage-allowlist.yml b/.github/ci-coverage-allowlist.yml
index 1423228e725..ccc21512e79 100644
--- a/.github/ci-coverage-allowlist.yml
+++ b/.github/ci-coverage-allowlist.yml
@@ -116,6 +116,14 @@ test_paths:
       - tests/load_tests/test_otel_load_test.py
       - tests/load_tests/test_vertex_embeddings_load_test.py
       - tests/load_tests/test_vertex_load_tests.py
+  - reason: >-
+      A local-only agent rig: test_a2a_completion_bridge.py needs a LangGraph server on
+      localhost:2024 and test_a2a.py drives a live A2A endpoint, so neither can run in a
+      pull request job. Until 2026-08-20 the CircleCI agent job hid them behind a grep -v
+      that this census could not see; the glob now excludes them structurally and this entry
+      is the decision on the record. Revisit when the A2A bridge gets a recorded-wire fixture
+    paths:
+      - tests/agent_tests/local_only_agent_tests
   - reason: >-
       Third-party integration tests that skip themselves without OCI configuration or sandbox
       credentials, neither of which a pull request job holds
diff --git a/.github/workflows/auto_update_price_and_context_window_file.py b/.github/scripts/auto_update_price_and_context_window_file.py
similarity index 100%
rename from .github/workflows/auto_update_price_and_context_window_file.py
rename to .github/scripts/auto_update_price_and_context_window_file.py
diff --git a/.github/workflows/run_llm_translation_tests.py b/.github/scripts/run_llm_translation_tests.py
similarity index 100%
rename from .github/workflows/run_llm_translation_tests.py
rename to .github/scripts/run_llm_translation_tests.py
diff --git a/.github/scripts/triage_rollout_heads_up.py b/.github/scripts/triage_rollout_heads_up.py
deleted file mode 100644
index a5dedb1c9e7..00000000000
--- a/.github/scripts/triage_rollout_heads_up.py
+++ /dev/null
@@ -1,557 +0,0 @@
-#!/usr/bin/env python3
-"""One-shot 7-day heads-up sweep for the Agent Shin rollout.
-
-Posts a friendly "the OSS triage bot kicks in next Monday" comment on every
-open external PR/issue that currently *would* fail the new rubric — i.e.,
-every PR/issue Agent Shin would close once the rollout completes. The point
-is to give contributors a full week to fix their description before the bot
-ever takes a destructive action, so nobody is surprised by an auto-close.
-
-The script is designed to run **exactly once** at rollout, fired by a manual
-``workflow_dispatch`` (``dry_run=false``) on the heads-up workflow. Re-runs
-are safe: every comment is stamped with the hidden ``HEADS_UP_MARKER`` and
-PRs/issues that already carry the marker are skipped.
-
-Dry-run vs. real run
---------------------
-Defaults to dry-run. Passing ``--close`` flips into real mode. Every GitHub
-mutation goes through ``_agent_shin_actions``, which has a one-line
-``if dry_run: log else: do_it`` per call, so the only difference between a
-dry-run preview and the real run is the call site that actually hits the
-GitHub API.
-
-Local preview::
-
-    python3 .github/scripts/triage_rollout_heads_up.py --repo BerriAI/litellm
-
-Real run (the manual rollout dispatch uses this)::
-
-    python3 .github/scripts/triage_rollout_heads_up.py --repo BerriAI/litellm --close
-"""
-
-from __future__ import annotations
-
-import argparse
-import datetime as dt
-import json
-import os
-import sys
-from pathlib import Path
-from typing import Any
-
-# Make the sibling triage_with_llm + _agent_shin_actions importable when this
-# script is invoked directly (the GitHub workflow does `python3 .github/scripts/...`).
-_SCRIPTS_DIR = Path(__file__).resolve().parent
-if str(_SCRIPTS_DIR) not in sys.path:
-    sys.path.insert(0, str(_SCRIPTS_DIR))
-
-from _agent_shin_actions import maybe_post_comment  # noqa: E402
-from agent_shin_shared import (  # noqa: E402
-    AGENT_SHIN_DEFAULT_BOT_LOGIN,
-    ALLOWLIST_LOGINS,
-    list_open_items,
-)
-from triage_with_llm import (  # noqa: E402
-    DEFAULT_MODEL,
-    call_llm_judge,
-    fetch_issue,
-    fetch_pr,
-    gh,
-    is_internal_contributor,
-    review_gate,
-    triage,
-)
-
-# Hidden marker so re-runs skip PRs/issues we've already notified. Distinct from
-# the within-grace / ready / regressed markers so it can't be confused with the
-# steady-state lifecycle comments.
-HEADS_UP_MARKER = "<!-- agent-shin:rollout-heads-up -->"
-
-# Placeholder until the litellm-docs PR ships. The rollout blog post explains
-# the new rubric, the 7-day grace, and how to recover after an auto-close.
-# TODO(docs): replace with the canonical URL once the litellm-docs PR merges.
-ROLLOUT_BLOG_URL = "https://docs.litellm.ai/docs/agent_shin_triage_rollout"
-
-# Default cutoff is one week from "now". Computed at runtime so the wording
-# stays correct even if the rollout is merged later than planned. The user can
-# override with --close-on YYYY-MM-DD when running the script manually.
-DEFAULT_GRACE_DAYS = 7
-
-# The daily auto-close sweeps (close_low_quality_prs.yml at 09:00 UTC and
-# review_gate.yml at 09:30 UTC) are what actually close a still-failing item,
-# so the deadline we promise contributors has to name that wall-clock moment.
-ACTIVATION_TIME_UTC = "09:00 UTC"
-
-
-def _format_cutoff(cutoff: dt.date) -> str:
-    """Human-readable, timezone-explicit cutoff, e.g. ``Monday, June 1, 2026
-    (09:00 UTC)`` — the moment a still-failing PR/issue gets closed."""
-    return (
-        f"{cutoff.strftime('%A, %B')} {cutoff.day}, {cutoff.year} "
-        f"({ACTIVATION_TIME_UTC})"
-    )
-
-
-def _rubric_section_pr() -> str:
-    return (
-        "**Going forward, every external PR needs ONE of:**\n"
-        "\n"
-        "- A linked GitHub issue using a closing keyword: "
-        "`Fixes #1234`, `Closes #1234`, or `Resolves #1234`, OR\n"
-        "- All three of: a clear **problem description**, **expected vs. "
-        "actual behavior**, and **end-to-end QA proof** (at least one of a "
-        "short screen recording / video, before/after screenshots, or the "
-        "exact commands you ran with their real output; mocked or stubbed "
-        "runs don't count).\n"
-        "\n"
-        "PRs also need a **Greptile confidence score of 4/5 or higher** before "
-        "the bot will tag them `ready for review`. You can `@greptileai` to "
-        "request a fresh review at any time, including after the PR is closed."
-    )
-
-
-def _rubric_section_issue() -> str:
-    return (
-        "**Going forward, every external issue needs:**\n"
-        "\n"
-        "- For **bug reports**: end-to-end evidence of the bug (at least one "
-        "of a screen recording / video, a screenshot, or the exact commands "
-        "you ran with their real output / traceback) plus expected vs. actual "
-        "behavior. Written steps with no run output don't count, and mocked "
-        "or stubbed runs don't count.\n"
-        "- For **feature requests**: a clear description of the proposed "
-        "feature plus a use case + concrete example (config, API call, UI "
-        "flow, or scenario showing what's blocked today)."
-    )
-
-
-def _description_only_note(kind: str) -> str:
-    noun = "PR" if kind == "pr" else "issue"
-    return (
-        f"⚠️ **The requirements must live in the {noun} *description*, not in "
-        "comments.** Some PRs/issues collect 100+ comments from humans and "
-        "bots; reading the entire thread on every triage run would balloon "
-        "GitHub API usage (we'd start getting 429'd) and blow out the LLM "
-        "judge's context. The bot only reads the description, so anything "
-        "you add as a comment will be invisible to it."
-    )
-
-
-def _missing_section(verdict: dict, greptile_score: int | None) -> str:
-    """Bullet list of what's currently missing on this PR/issue.
-
-    Combines the LLM judge's `missing` list (rubric items) with a Greptile
-    shortfall (for PRs) so the contributor sees one list of things to fix.
-    """
-    missing = list(verdict.get("missing") or [])
-    if greptile_score is not None and greptile_score < 4:
-        missing.insert(
-            0,
-            f"Greptile's most recent review scored this PR {greptile_score}/5 "
-            "(below the 4/5 bar Agent Shin will require).",
-        )
-    if not missing:
-        return (
-            "_The bot couldn't articulate a specific missing piece; see the "
-            "rubric link above and double-check the description includes all "
-            "of it before the rollout._"
-        )
-    bullets = "\n".join(f"- {m}" for m in missing)
-    return f"**What this one is currently missing:**\n\n{bullets}"
-
-
-def _recovery_section(kind: str) -> str:
-    if kind == "pr":
-        return (
-            "**If the bot closes this PR after the rollout:** update the "
-            "description with the missing pieces, then either open a fresh "
-            "PR or comment `@agent-shin reconsider` on the closed PR. If "
-            "Greptile re-scores you at 4/5 or higher I'll reopen and tag "
-            "the PR `ready for review`. (`@greptileai` works on closed PRs "
-            "too; a fresh review is one of the signals that lifts you back "
-            "into the queue.) This is **not** us losing interest in your "
-            "change; far from it. We just need open PRs to be a list of "
-            "things a maintainer can act on, so we can get to yours faster."
-        )
-    return (
-        "**If the bot closes this issue after the rollout:** edit the issue "
-        "description to add the missing pieces, then comment `@agent-shin "
-        "reconsider` on the closed issue. I'll re-evaluate and, if the rubric "
-        "is met, reopen it. (GitHub doesn't let external authors reopen an "
-        "issue a maintainer or bot closed, so the comment is the reliable "
-        "path.) This is **not** us saying the bug isn't real or the request "
-        "isn't useful; it's so the remaining open issues are a list of things "
-        "a maintainer can act on."
-    )
-
-
-def format_heads_up_comment(
-    *, kind: str, verdict: dict, greptile_score: int | None, cutoff: dt.date
-) -> str:
-    """Compose the friendly 7-day heads-up comment posted on a failing PR/issue."""
-    noun = "PR" if kind == "pr" else "issue"
-    rubric = _rubric_section_pr() if kind == "pr" else _rubric_section_issue()
-    cutoff_str = _format_cutoff(cutoff)
-    explanation = (verdict.get("explanation") or "").strip()
-    explanation_block = (
-        f"> _(The judge's note for this one: {explanation})_\n\n" if explanation else ""
-    )
-
-    return (
-        "🚅 **Heads-up: we're turning on the OSS triage bot in "
-        f"{DEFAULT_GRACE_DAYS} days, on {cutoff_str}.**\n"
-        "\n"
-        "We're rolling out **Agent Shin**, an LLM-as-judge triage bot for "
-        f"external {noun}s. Once it's live, the bot reads each open "
-        f"{noun}'s description, scores it against a small rubric, and "
-        f"auto-closes any {noun} that's missing the basics, with a single "
-        f"comment explaining what's missing and how to recover. Full "
-        f"context: [Agent Shin rollout blog post]({ROLLOUT_BLOG_URL}).\n"
-        "\n"
-        f"{rubric}\n"
-        "\n"
-        f"{_description_only_note(kind)}\n"
-        "\n"
-        f"{_missing_section(verdict, greptile_score)}\n"
-        "\n"
-        f"{explanation_block}"
-        "**Timeline (you have a week):**\n"
-        "\n"
-        f"- We turn the bot on in {DEFAULT_GRACE_DAYS} days, on "
-        f"**{cutoff_str}**. You have until then to update this {noun}'s "
-        "description with the missing pieces above.\n"
-        f"- If this {noun} still fails the rubric at **{cutoff_str}**, "
-        "we'll close it.\n"
-        f"- From then on the bot runs daily, and every {noun} that fails "
-        "the rubric gets a **2-hour lifetime**: one warning comment, then "
-        "auto-close 2 hours later.\n"
-        "\n"
-        f"{_recovery_section(kind)}\n"
-        "\n"
-        f"{HEADS_UP_MARKER}"
-    )
-
-
-def _list_open_numbers(repo: str, kind: str) -> list[int]:
-    """Return every open PR or issue number in ``repo``.
-
-    Delegates to ``list_open_items`` so the full backlog is fetched (no cap)
-    and the `gh {pr,issue} list` invocation stays in one shared place. ``gh
-    issue list`` would include PRs, but ``list_open_items`` uses the dedicated
-    command per kind, so the two never mix.
-    """
-    return [
-        item["number"] for item in list_open_items(kind, repo=repo, fields="number")
-    ]
-
-
-def _has_heads_up_marker(item: dict) -> bool:
-    """Cheap fast-path: check the PR/issue body itself for the marker.
-
-    The marker is appended to the *comment* we post, not the body, so this
-    will only fire if the body literally contains the marker text. We still
-    do the comment-marker check separately below; this body check just lets
-    us short-circuit for PRs/issues that quote the marker for any reason.
-    """
-    body = item.get("body") or ""
-    return HEADS_UP_MARKER in body
-
-
-def _comments_have_marker(repo: str, number: int) -> bool:
-    """True if the bot already posted a comment carrying the marker.
-
-    Used for idempotency: a re-run skips items the previous run notified.
-    Filters by author (matching the sibling marker-checks in
-    ``triage_with_llm._has_marker`` and
-    ``agent_shin_shared.seconds_since_latest_marker_comment``) so a
-    contributor who quotes the heads-up via GitHub's "Quote reply" — which
-    preserves HTML comments in the raw markdown — can't trick the
-    idempotency check into silently skipping a real heads-up.
-
-    Comments live on the unified issues endpoint regardless of whether the
-    item is a PR or an issue, so no ``kind`` argument is required here.
-    """
-    expected_login = (
-        os.environ.get("AGENT_SHIN_BOT_LOGIN") or AGENT_SHIN_DEFAULT_BOT_LOGIN
-    ).lower()
-    raw = gh(
-        "api",
-        "--paginate",
-        f"repos/{repo}/issues/{number}/comments?per_page=100",
-    )
-    for line in raw.splitlines():
-        line = line.strip()
-        if not line:
-            continue
-        try:
-            payload = json.loads(line)
-        except json.JSONDecodeError:
-            continue
-        comments = payload if isinstance(payload, list) else [payload]
-        for comment in comments:
-            author = ((comment.get("user") or {}).get("login") or "").lower()
-            if author != expected_login:
-                continue
-            if HEADS_UP_MARKER in (comment.get("body") or ""):
-                return True
-    return False
-
-
-def _evaluate_pr(*, repo: str, number: int, model: str, judge: Any = None) -> dict:
-    """Run the future PR rubric (review_gate) in dry-run and return the result."""
-    return review_gate(
-        repo=repo,
-        number=number,
-        close=False,  # we only want the verdict, never act here
-        model=model,
-        judge=judge,
-    )
-
-
-def _evaluate_issue(*, repo: str, number: int, model: str, judge: Any = None) -> dict:
-    """Run the future issue rubric (triage kind='issue') in dry-run."""
-    return triage(
-        repo=repo,
-        kind="issue",
-        number=number,
-        close=False,
-        model=model,
-        judge=judge,
-    )
-
-
-def _would_be_closed(kind: str, result: dict) -> bool:
-    """True if the future triage would auto-close this PR/issue based on the
-    rubric (regardless of grace-period gating).
-
-    For PRs we trust ``review_gate``'s ``passing`` field — it combines the LLM
-    verdict and the Greptile score. For issues we read the LLM verdict
-    directly. Both fields are ``None``/missing on skip paths
-    (skip-internal-author, skip-llm-error, etc.) where the future bot would
-    NOT close the item — those return False.
-    """
-    if kind == "pr":
-        passing = result.get("passing")
-        if passing is None:
-            return False  # skipped — nothing for the heads-up to warn about
-        return passing is False
-    verdict = result.get("verdict") or {}
-    return (verdict.get("verdict") or "").lower() == "fail"
-
-
-def _process_one(
-    *,
-    repo: str,
-    kind: str,
-    number: int,
-    model: str,
-    cutoff: dt.date,
-    dry_run: bool,
-    judge: Any = None,
-    skip_marker_check: bool = False,
-    allowlist: frozenset[str] = ALLOWLIST_LOGINS,
-) -> dict:
-    """Evaluate one PR/issue and post a heads-up if it would be auto-closed.
-
-    Returns a per-item dict for the summary table.
-    """
-    base = {"kind": kind, "number": number}
-    fetcher = fetch_pr if kind == "pr" else fetch_issue
-    item = fetcher(repo, number)
-
-    if (item.get("state") or "") != "open":
-        return {**base, "action": "skip-not-open"}
-    if allowlist:
-        login = (item.get("user") or {}).get("login") or ""
-        if login.lower() not in allowlist:
-            return {**base, "action": "skip-not-allowlisted"}
-    elif is_internal_contributor(item):
-        return {**base, "action": "skip-internal-author"}
-    if not skip_marker_check and _has_heads_up_marker(item):
-        return {**base, "action": "skip-already-marked-in-body"}
-    if not skip_marker_check and _comments_have_marker(repo, number):
-        return {**base, "action": "skip-already-notified"}
-
-    if kind == "pr":
-        result = _evaluate_pr(repo=repo, number=number, model=model, judge=judge)
-    else:
-        result = _evaluate_issue(repo=repo, number=number, model=model, judge=judge)
-
-    if not _would_be_closed(kind, result):
-        return {**base, "action": "skip-passing", "evaluator": result.get("action")}
-
-    verdict = result.get("verdict") or {}
-    greptile_score = result.get("greptile_score") if kind == "pr" else None
-    comment = format_heads_up_comment(
-        kind=kind, verdict=verdict, greptile_score=greptile_score, cutoff=cutoff
-    )
-    maybe_post_comment(repo, number, comment, dry_run=dry_run)
-    return {
-        **base,
-        "action": "heads-up-posted" if not dry_run else "would-post-heads-up",
-        "verdict": (verdict.get("verdict") or "").lower(),
-        "greptile_score": greptile_score,
-    }
-
-
-def _print_summary(results: list[dict]) -> None:
-    """Tally per-action counts so a dry-run preview tells you at a glance how
-    many comments the real run would post."""
-    counts: dict[str, int] = {}
-    for r in results:
-        counts[r["action"]] = counts.get(r["action"], 0) + 1
-    print("\n=== rollout heads-up summary ===")
-    for action in sorted(counts):
-        print(f"  {action:35s} {counts[action]}")
-    print(f"  total                                {len(results)}")
-
-
-def run(
-    *,
-    repo: str,
-    close: bool,
-    cutoff: dt.date,
-    model: str,
-    kinds: tuple[str, ...] = ("pr", "issue"),
-    judge: Any = None,
-    only_numbers: dict[str, list[int]] | None = None,
-    skip_marker_check: bool = False,
-) -> list[dict]:
-    """Sweep ``repo`` and post heads-up comments. Returns the per-item results."""
-    dry_run = not close
-    if dry_run:
-        print(
-            f"[DRY RUN] sweeping {repo}; --close not passed, no comments will be posted."
-        )
-    else:
-        print(f"[REAL RUN] sweeping {repo}; comments WILL be posted.")
-    print(f"Cutoff date in comment body: {cutoff.isoformat()}")
-
-    results: list[dict] = []
-    for kind in kinds:
-        if only_numbers and kind in only_numbers:
-            numbers = list(only_numbers[kind])
-        else:
-            numbers = _list_open_numbers(repo, kind)
-        print(f"\n--- {kind}s: {len(numbers)} open ---")
-        for n in numbers:
-            try:
-                result = _process_one(
-                    repo=repo,
-                    kind=kind,
-                    number=n,
-                    model=model,
-                    cutoff=cutoff,
-                    dry_run=dry_run,
-                    judge=judge,
-                    skip_marker_check=skip_marker_check,
-                )
-            except (
-                Exception
-            ) as exc:  # noqa: BLE001 - per-item errors don't abort the sweep
-                result = {
-                    "kind": kind,
-                    "number": n,
-                    "action": "error",
-                    "error": str(exc),
-                }
-                print(f"!! {kind}#{n}: {exc}", file=sys.stderr)
-            print(f"  {kind}#{n}: {result['action']}")
-            results.append(result)
-    _print_summary(results)
-    return results
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--repo", required=True, help="owner/repo")
-    parser.add_argument(
-        "--close",
-        action="store_true",
-        help=(
-            "Actually post comments. Without this flag the script is in "
-            "dry-run mode and only logs what it would do."
-        ),
-    )
-    parser.add_argument(
-        "--close-on",
-        type=dt.date.fromisoformat,
-        default=None,
-        help=(
-            "Cutoff date shown in the heads-up comment as the rollout date "
-            f"(default: today + {DEFAULT_GRACE_DAYS} days)."
-        ),
-    )
-    parser.add_argument(
-        "--model",
-        default=os.environ.get("TRIAGE_MODEL") or DEFAULT_MODEL,
-        help=f"Model for the rubric LLM judge (default: {DEFAULT_MODEL}).",
-    )
-    parser.add_argument(
-        "--kind",
-        choices=("pr", "issue", "both"),
-        default="both",
-        help="Restrict the sweep to PRs or issues only (default: both).",
-    )
-    parser.add_argument(
-        "--only-pr",
-        type=int,
-        action="append",
-        default=[],
-        help="Limit the PR sweep to these PR numbers (repeat for several).",
-    )
-    parser.add_argument(
-        "--only-issue",
-        type=int,
-        action="append",
-        default=[],
-        help="Limit the issue sweep to these issue numbers (repeat for several).",
-    )
-    parser.add_argument(
-        "--ignore-existing-marker",
-        action="store_true",
-        help=(
-            "Re-post on PRs/issues that already carry the heads-up marker. "
-            "Useful for testing the comment wording on a known PR."
-        ),
-    )
-    args = parser.parse_args()
-
-    cutoff = args.close_on or (
-        dt.datetime.now(dt.timezone.utc).date() + dt.timedelta(days=DEFAULT_GRACE_DAYS)
-    )
-
-    kinds: tuple[str, ...]
-    if args.kind == "pr":
-        kinds = ("pr",)
-    elif args.kind == "issue":
-        kinds = ("issue",)
-    else:
-        kinds = ("pr", "issue")
-
-    only: dict[str, list[int]] = {}
-    if args.only_pr:
-        only["pr"] = args.only_pr
-    if args.only_issue:
-        only["issue"] = args.only_issue
-
-    # The script must NOT hit the LLM in dry-run if no key is set — we still
-    # want a useful preview that says "skip-no-llm-key" for items that would
-    # have been judged. Production runs require OPENAI_API_KEY.
-    if args.close and not os.environ.get("OPENAI_API_KEY"):
-        parser.error("OPENAI_API_KEY must be set for --close (real-run) mode.")
-
-    run(
-        repo=args.repo,
-        close=args.close,
-        cutoff=cutoff,
-        model=args.model,
-        kinds=kinds,
-        only_numbers=only or None,
-        skip_marker_check=args.ignore_existing_marker,
-    )
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())
diff --git a/.github/workflows/auto_update_price_and_context_window.yml b/.github/workflows/auto_update_price_and_context_window.yml
index d391c0bd6ce..7e40a860ee9 100644
--- a/.github/workflows/auto_update_price_and_context_window.yml
+++ b/.github/workflows/auto_update_price_and_context_window.yml
@@ -23,7 +23,7 @@ jobs:
           version: "0.10.9"
       - name: Update JSON Data
         run: |
-          uv run --frozen --with 'aiohttp==3.13.3' python ".github/workflows/auto_update_price_and_context_window_file.py"
+          uv run --frozen --with 'aiohttp==3.13.3' python ".github/scripts/auto_update_price_and_context_window_file.py"
       - name: Regenerate JSON Schema
         run: |
           uv run --frozen python ci_cd/generate_model_prices_schema.py
diff --git a/.github/workflows/triage_rollout_heads_up.yml b/.github/workflows/triage_rollout_heads_up.yml
deleted file mode 100644
index 903960151e2..00000000000
--- a/.github/workflows/triage_rollout_heads_up.yml
+++ /dev/null
@@ -1,92 +0,0 @@
-name: Agent Shin — rollout heads-up (one-shot)
-
-# Fires the 7-day heads-up comment on every open external PR/issue that the
-# new triage bot would auto-close. The real sweep is a deliberate one-shot:
-# trigger it at rollout via a manual `workflow_dispatch` with `dry_run=false`.
-# The script is idempotent (skips items that already carry the
-# `<!-- agent-shin:rollout-heads-up -->` marker), so a re-run is harmless.
-#
-# The automatic push trigger runs DRY-RUN only, so merging the script to
-# `litellm_internal_staging` never posts a comment; it just confirms the
-# workflow is wired up. Posting real comments requires the manual dispatch,
-# which is also the only trigger that exposes `OPENAI_API_KEY`. The heads-up
-# is intentionally NOT gated on `AGENT_SHIN_ENABLED`: it has to warn
-# contributors while that flag is still off, ahead of the flip that turns on
-# auto-closing.
-#
-# The workflow is a thin shell over `.github/scripts/triage_rollout_heads_up.py`.
-# Dry-run vs. real run differ in EXACTLY one CLI flag (`--close`), added only
-# on a manual dispatch with `dry_run=false`.
-
-on:
-  push:
-    branches:
-      - litellm_internal_staging
-    paths:
-      # The presence of this script on staging IS the rollout merge marker.
-      # Editing the file later would re-fire the workflow; that's safe because
-      # the script skips PRs/issues that already have the heads-up marker.
-      - ".github/scripts/triage_rollout_heads_up.py"
-  workflow_dispatch:
-    inputs:
-      dry_run:
-        description: "Dry run (true = preview only, false = actually post comments)."
-        required: false
-        default: "true"
-        type: choice
-        options:
-          - "true"
-          - "false"
-
-permissions:
-  contents: read
-  issues: write
-  pull-requests: write
-
-jobs:
-  heads-up:
-    if: github.repository == 'BerriAI/litellm'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout triage scripts
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          sparse-checkout: .github/scripts
-          persist-credentials: false
-
-      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
-        with:
-          python-version: "3.12"
-
-      - name: Install LLM client
-        run: pip install --no-cache-dir --require-hashes -r .github/scripts/triage-requirements.txt
-
-      - name: Run heads-up sweep
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Only the manual dispatch (the real-run trigger) needs the LLM key.
-          # The automatic push trigger runs dry-run and never posts, so it gets
-          # no key. Mirrors the sibling triage workflows, which expose the key
-          # only on an enabled/dispatched run rather than unconditionally.
-          OPENAI_API_KEY: ${{ github.event_name == 'workflow_dispatch' && secrets.OPENAI_API_KEY || '' }}
-          OPENAI_BASE_URL: ${{ vars.OPENAI_BASE_URL }}
-          TRIAGE_MODEL: ${{ vars.TRIAGE_MODEL }}
-          # The real run is a deliberate manual dispatch with dry_run=false.
-          # Use the EXACT "false" comparison so any unexpected input value
-          # fail-closes to dry-run (mirrors the AGENT_SHIN_ENABLED pattern in
-          # the sibling workflows). The automatic push trigger always stays
-          # dry-run, so merging the script never posts.
-          DRY_RUN_INPUT: ${{ github.event.inputs.dry_run }}
-        run: |
-          set -euo pipefail
-          ARGS=(--repo "${{ github.repository }}")
-          if [ "${GITHUB_EVENT_NAME:-}" = "workflow_dispatch" ] && [ "${DRY_RUN_INPUT:-true}" = "false" ]; then
-            ARGS+=(--close)
-            echo "::notice::Manual rollout dispatch with dry_run=false -> heads-up comments WILL be posted."
-          elif [ "${GITHUB_EVENT_NAME:-}" = "workflow_dispatch" ]; then
-            echo "::notice::Manual dispatch in dry-run mode -> previewing only, no comments will be posted."
-          else
-            echo "::notice::Automatic push trigger -> dry-run preview only. Fire the real rollout sweep with a manual workflow_dispatch (dry_run=false)."
-          fi
-          python3 .github/scripts/triage_rollout_heads_up.py "${ARGS[@]}"
diff --git a/Makefile b/Makefile
index 5e5f7c80027..6c125268678 100644
--- a/Makefile
+++ b/Makefile
@@ -314,7 +314,7 @@ test-unit-helm: install-helm-unittest
 # LLM Translation testing targets
 test-llm-translation: install-test-deps
 	@echo "Running LLM translation tests..."
-	@python .github/workflows/run_llm_translation_tests.py
+	@python .github/scripts/run_llm_translation_tests.py
 
 test-llm-translation-single: install-test-deps
 	@echo "Running single LLM translation test file..."
diff --git a/tests/scim_tests/scim_e2e_test.json b/tests/scim_tests/scim_e2e_test.json
deleted file mode 100644
index bc5810762da..00000000000
--- a/tests/scim_tests/scim_e2e_test.json
+++ /dev/null
@@ -1,750 +0,0 @@
-{
-    "version": "1.0",
-    "exported_at": 1715608731,
-    "name": "Okta SCIM 2.0 SPEC Test",
-    "description": "Basic tests to see if your SCIM server will work with Okta",
-    "trigger_url": "https://api.runscope.com/radar/37d9f10e-e250-4071-9cec-1fa30e56b42b/trigger",
-    "steps": [
-      {
-        "step_type": "request",
-        "skipped": false,
-        "note": "Required Test: Test Users endpoint",
-        "auth": {},
-        "multipart_form": [],
-        "headers": {
-          "Accept-Charset": [
-            "utf-8"
-          ],
-          "Content-Type": [
-            "application/scim+json; charset=utf-8"
-          ],
-          "Accept": [
-            "application/scim+json"
-          ],
-          "Authorization": [
-            "{{auth}}"
-          ],
-          "User-Agent": [
-            "OKTA SCIM Integration"
-          ]
-        },
-        "method": "GET",
-        "url": "{{SCIMBaseURL}}/Users?count=1&startIndex=1",
-        "assertions": [
-          {
-            "comparison": "equal_number",
-            "source": "response_status",
-            "value": "200"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "Resources"
-          },
-          {
-            "comparison": "has_value",
-            "source": "response_json",
-            "value": "urn:ietf:params:scim:api:messages:2.0:ListResponse",
-            "property": "schemas"
-          },
-          {
-            "comparison": "is_a_number",
-            "source": "response_json",
-            "value": null,
-            "property": "itemsPerPage"
-          },
-          {
-            "comparison": "is_a_number",
-            "source": "response_json",
-            "value": null,
-            "property": "startIndex"
-          },
-          {
-            "comparison": "is_a_number",
-            "source": "response_json",
-            "value": null,
-            "property": "totalResults"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "Resources[0].id"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "Resources[0].name.familyName"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "Resources[0].name.givenName"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "Resources[0].userName"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "Resources[0].active"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "Resources[0].emails[0].value"
-          }
-        ],
-        "variables": [
-          {
-            "source": "response_json",
-            "name": "ISVUserid",
-            "property": "Resources[0].id"
-          }
-        ],
-        "scripts": [],
-        "before_scripts": []
-      },
-      {
-        "step_type": "pause",
-        "skipped": false,
-        "duration": 5
-      },
-      {
-        "step_type": "request",
-        "skipped": false,
-        "note": "Required Test: Get Users/{{id}} ",
-        "auth": {},
-        "multipart_form": [],
-        "headers": {
-          "Accept-Charset": [
-            "utf-8"
-          ],
-          "Content-Type": [
-            "application/scim+json; charset=utf-8"
-          ],
-          "Accept": [
-            "application/scim+json"
-          ],
-          "Authorization": [
-            "{{auth}}"
-          ],
-          "User-Agent": [
-            "OKTA SCIM Integration"
-          ]
-        },
-        "method": "GET",
-        "url": "{{SCIMBaseURL}}/Users/{{ISVUserid}}",
-        "assertions": [
-          {
-            "comparison": "equal_number",
-            "source": "response_status",
-            "value": "200"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "id"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "name.familyName"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "name.givenName"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "userName"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "active"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "emails[0].value"
-          },
-          {
-            "comparison": "equal",
-            "source": "response_json",
-            "value": "{{ISVUserid}}",
-            "property": "id"
-          }
-        ],
-        "variables": [],
-        "scripts": [],
-        "before_scripts": []
-      },
-      {
-        "step_type": "pause",
-        "skipped": false,
-        "duration": 5
-      },
-      {
-        "step_type": "request",
-        "skipped": false,
-        "note": "Required Test: Test invalid User by username",
-        "auth": {},
-        "multipart_form": [],
-        "headers": {
-          "Accept-Charset": [
-            "utf-8"
-          ],
-          "Content-Type": [
-            "application/scim+json; charset=utf-8"
-          ],
-          "Accept": [
-            "application/scim+json"
-          ],
-          "Authorization": [
-            "{{auth}}"
-          ],
-          "User-Agent": [
-            "OKTA SCIM Integration"
-          ]
-        },
-        "method": "GET",
-        "url": "{{SCIMBaseURL}}/Users?filter=userName eq \"{{InvalidUserEmail}}\"",
-        "assertions": [
-          {
-            "comparison": "equal_number",
-            "source": "response_status",
-            "value": "200"
-          },
-          {
-            "comparison": "has_value",
-            "source": "response_json",
-            "value": "urn:ietf:params:scim:api:messages:2.0:ListResponse",
-            "property": "schemas"
-          },
-          {
-            "comparison": "equal",
-            "source": "response_json",
-            "value": "0",
-            "property": "totalResults"
-          }
-        ],
-        "variables": [],
-        "scripts": [],
-        "before_scripts": []
-      },
-      {
-        "step_type": "pause",
-        "skipped": false,
-        "duration": 5
-      },
-      {
-        "step_type": "request",
-        "skipped": false,
-        "note": "Required Test: Test invalid User by ID",
-        "auth": {},
-        "multipart_form": [],
-        "headers": {
-          "Accept-Charset": [
-            "utf-8"
-          ],
-          "Content-Type": [
-            "application/scim+json; charset=utf-8"
-          ],
-          "Authorization": [
-            "{{auth}}"
-          ],
-          "Accept": [
-            "application/scim+json"
-          ],
-          "User-Agent": [
-            "OKTA SCIM Integration"
-          ]
-        },
-        "method": "GET",
-        "url": "{{SCIMBaseURL}}/Users/{{UserIdThatDoesNotExist}}",
-        "assertions": [
-          {
-            "comparison": "equal_number",
-            "source": "response_status",
-            "value": "404"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "detail"
-          },
-          {
-            "comparison": "has_value",
-            "source": "response_json",
-            "value": "urn:ietf:params:scim:api:messages:2.0:Error",
-            "property": "schemas"
-          }
-        ],
-        "variables": [],
-        "scripts": [],
-        "before_scripts": []
-      },
-      {
-        "step_type": "pause",
-        "skipped": false,
-        "duration": 5
-      },
-      {
-        "step_type": "request",
-        "skipped": false,
-        "note": "Required Test: Make sure random user doesn't exist",
-        "auth": {},
-        "multipart_form": [],
-        "headers": {
-          "Accept-Charset": [
-            "utf-8"
-          ],
-          "Content-Type": [
-            "application/scim+json; charset=utf-8"
-          ],
-          "Authorization": [
-            "{{auth}}"
-          ],
-          "Accept": [
-            "application/scim+json"
-          ],
-          "User-Agent": [
-            "OKTA SCIM Integration"
-          ]
-        },
-        "method": "GET",
-        "url": "{{SCIMBaseURL}}/Users?filter=userName eq \"{{randomEmail}}\"",
-        "assertions": [
-          {
-            "comparison": "equal_number",
-            "source": "response_status",
-            "value": "200"
-          },
-          {
-            "comparison": "equal_number",
-            "source": "response_json",
-            "value": "0",
-            "property": "totalResults"
-          },
-          {
-            "comparison": "has_value",
-            "source": "response_json",
-            "value": "urn:ietf:params:scim:api:messages:2.0:ListResponse",
-            "property": "schemas"
-          }
-        ],
-        "variables": [],
-        "scripts": [],
-        "before_scripts": []
-      },
-      {
-        "step_type": "pause",
-        "skipped": false,
-        "duration": 5
-      },
-      {
-        "step_type": "request",
-        "skipped": false,
-        "note": "Required Test: Create Okta user with realistic values",
-        "auth": {},
-        "body": "{\"schemas\":[\"urn:ietf:params:scim:schemas:core:2.0:User\"],\"userName\":\"{{randomUsername}}\",\"name\":{\"givenName\":\"{{randomGivenName}}\",\"familyName\":\"{{randomFamilyName}}\"},\"emails\":[{\"primary\":true,\"value\":\"{{randomEmail}}\",\"type\":\"work\"}],\"displayName\":\"{{randomGivenName}} {{randomFamilyName}}\",\"active\":true}",
-        "form": {},
-        "multipart_form": [],
-        "binary_body": null,
-        "headers": {
-          "Content-Type": [
-            "application/json"
-          ],
-          "Authorization": [
-            "{{auth}}"
-          ],
-          "Accept": [
-            "application/scim+json; charset=utf-8"
-          ]
-        },
-        "method": "POST",
-        "url": "{{SCIMBaseURL}}/Users",
-        "assertions": [
-          {
-            "comparison": "equal_number",
-            "source": "response_status",
-            "value": "201"
-          },
-          {
-            "comparison": "equal",
-            "source": "response_json",
-            "value": "true",
-            "property": "active"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "id"
-          },
-          {
-            "comparison": "equal",
-            "source": "response_json",
-            "value": "{{randomFamilyName}}",
-            "property": "name.familyName"
-          },
-          {
-            "comparison": "equal",
-            "source": "response_json",
-            "value": "{{randomGivenName}}",
-            "property": "name.givenName"
-          },
-          {
-            "comparison": "contains",
-            "source": "response_json",
-            "value": "urn:ietf:params:scim:schemas:core:2.0:User",
-            "property": "schemas"
-          },
-          {
-            "comparison": "equal",
-            "source": "response_json",
-            "value": "{{randomUsername}}",
-            "property": "userName"
-          }
-        ],
-        "variables": [
-          {
-            "source": "response_json",
-            "name": "idUserOne",
-            "property": "id"
-          },
-          {
-            "source": "response_json",
-            "name": "randomUserEmail",
-            "property": "emails[0].value"
-          }
-        ],
-        "scripts": [
-          ""
-        ],
-        "before_scripts": []
-      },
-      {
-        "step_type": "pause",
-        "skipped": false,
-        "duration": 5
-      },
-      {
-        "step_type": "request",
-        "skipped": false,
-        "note": "Required Test: Verify that user was created",
-        "auth": {},
-        "multipart_form": [],
-        "headers": {
-          "Accept-Charset": [
-            "utf-8"
-          ],
-          "Content-Type": [
-            "application/scim+json; charset=utf-8"
-          ],
-          "Authorization": [
-            "{{auth}}"
-          ],
-          "Accept": [
-            "application/scim+json"
-          ],
-          "User-Agent": [
-            "OKTA SCIM Integration"
-          ]
-        },
-        "method": "GET",
-        "url": "{{SCIMBaseURL}}/Users/{{idUserOne}}",
-        "assertions": [
-          {
-            "comparison": "equal_number",
-            "source": "response_status",
-            "value": "200"
-          },
-          {
-            "comparison": "equal",
-            "source": "response_json",
-            "value": "{{randomUsername}}",
-            "property": "userName"
-          },
-          {
-            "comparison": "equal",
-            "source": "response_json",
-            "value": "{{randomFamilyName}}",
-            "property": "name.familyName"
-          },
-          {
-            "comparison": "equal",
-            "source": "response_json",
-            "value": "{{randomGivenName}}",
-            "property": "name.givenName"
-          }
-        ],
-        "variables": [],
-        "scripts": [],
-        "before_scripts": []
-      },
-      {
-        "step_type": "pause",
-        "skipped": false,
-        "duration": 10
-      },
-      {
-        "step_type": "request",
-        "skipped": false,
-        "note": "Required Test: Expect failure when recreating user with same values",
-        "auth": {},
-        "body": "{\"schemas\":[\"urn:ietf:params:scim:schemas:core:2.0:User\"],\"userName\":\"{{randomUsername}}\",\"name\":{\"givenName\":\"{{randomGivenName}}\",\"familyName\":\"{{randomFamilyName}}\"},\"emails\":[{\"primary\":true,\"value\":\"{{randomUsername}}\",\"type\":\"work\"}],\"displayName\":\"{{randomGivenName}} {{randomFamilyName}}\",\"active\":true}",
-        "form": {},
-        "multipart_form": [],
-        "binary_body": null,
-        "headers": {
-          "Content-Type": [
-            "application/json"
-          ],
-          "Authorization": [
-            "{{auth}}"
-          ],
-          "Accept": [
-            "application/scim+json; charset=utf-8"
-          ]
-        },
-        "method": "POST",
-        "url": "{{SCIMBaseURL}}/Users",
-        "assertions": [
-          {
-            "comparison": "equal_number",
-            "source": "response_status",
-            "value": "409"
-          }
-        ],
-        "variables": [],
-        "scripts": [],
-        "before_scripts": []
-      },
-      {
-        "step_type": "pause",
-        "skipped": false,
-        "duration": 5
-      },
-      {
-        "step_type": "request",
-        "skipped": false,
-        "note": "Required Test: Username Case Sensitivity Check",
-        "auth": {},
-        "multipart_form": [],
-        "headers": {
-          "Accept-Charset": [
-            "utf-8"
-          ],
-          "Content-Type": [
-            "application/scim+json; charset=utf-8"
-          ],
-          "Authorization": [
-            "{{auth}}"
-          ],
-          "Accept": [
-            "application/scim+json"
-          ],
-          "User-Agent": [
-            "OKTA SCIM Integration"
-          ]
-        },
-        "method": "GET",
-        "url": "{{SCIMBaseURL}}/Users?filter=userName eq \"{{randomUsernameCaps}}\"",
-        "assertions": [
-          {
-            "comparison": "equal_number",
-            "source": "response_status",
-            "value": "200"
-          }
-        ],
-        "variables": [],
-        "scripts": [],
-        "before_scripts": []
-      },
-      {
-        "step_type": "pause",
-        "skipped": false,
-        "duration": 5
-      },
-      {
-        "step_type": "request",
-        "skipped": false,
-        "note": "Optional Test: Verify Groups endpoint",
-        "auth": {},
-        "multipart_form": [],
-        "headers": {
-          "Accept-Charset": [
-            "utf-8"
-          ],
-          "Content-Type": [
-            "application/scim+json; charset=utf-8"
-          ],
-          "Accept": [
-            "application/scim+json"
-          ],
-          "Authorization": [
-            "{{auth}}"
-          ],
-          "User-Agent": [
-            "OKTA SCIM Integration"
-          ]
-        },
-        "method": "GET",
-        "url": "{{SCIMBaseURL}}/Groups",
-        "assertions": [
-          {
-            "comparison": "equal_number",
-            "source": "response_status",
-            "value": "200"
-          },
-          {
-            "comparison": "is_less_than",
-            "source": "response_time",
-            "value": "600"
-          }
-        ],
-        "variables": [],
-        "scripts": [
-          "var data = JSON.parse(response.body);\nvar max = data.totalResults;\nvar res = data.Resources;\nvar exists = false;\n\nif (max === 0)\n\tassert(\"nogroups\", \"No Groups found in the endpoint\");\nelse if (max >= 1 && Array.isArray(res)) {\n    exists = true;\n    assert.ok(exists, \"Resources is of type Array\");\n\tlog(exists);\n}"
-        ],
-        "before_scripts": []
-      },
-      {
-        "step_type": "pause",
-        "skipped": false,
-        "duration": 5
-      },
-      {
-        "step_type": "request",
-        "skipped": false,
-        "note": "Required Test: Check status 401",
-        "multipart_form": [],
-        "headers": {
-          "Accept": [
-            "application/scim+json"
-          ],
-          "Accept-Charset": [
-            "utf-8"
-          ],
-          "Authorization": [
-            "non-token"
-          ],
-          "Content-Type": [
-            "application/scim+json; charset=utf-8"
-          ],
-          "User-Agent": [
-            "OKTA SCIM Integration"
-          ]
-        },
-        "auth": {},
-        "method": "GET",
-        "url": "{{SCIMBaseURL}}/Users?filter=userName eq \"{{randomUsernameCaps}}\"",
-        "assertions": [
-          {
-            "comparison": "equal_number",
-            "source": "response_status",
-            "value": "401"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "detail"
-          },
-          {
-            "comparison": "equal",
-            "source": "response_json",
-            "value": "401",
-            "property": "status"
-          },
-          {
-            "comparison": "has_value",
-            "source": "response_json",
-            "value": "urn:ietf:params:scim:api:messages:2.0:Error",
-            "property": "schemas"
-          }
-        ],
-        "variables": [],
-        "scripts": [],
-        "before_scripts": []
-      },
-      {
-        "step_type": "pause",
-        "skipped": false,
-        "duration": 5
-      },
-      {
-        "step_type": "request",
-        "skipped": false,
-        "note": "Required Test: Check status 404",
-        "multipart_form": [],
-        "headers": {
-          "Accept": [
-            "application/scim+json"
-          ],
-          "Accept-Charset": [
-            "utf-8"
-          ],
-          "Authorization": [
-            "{{auth}}"
-          ],
-          "Content-Type": [
-            "application/scim+json; charset=utf-8"
-          ],
-          "User-Agent": [
-            "OKTA SCIM Integration"
-          ]
-        },
-        "auth": {},
-        "method": "GET",
-        "url": "{{SCIMBaseURL}}/Users/00919288221112222",
-        "assertions": [
-          {
-            "comparison": "equal_number",
-            "source": "response_status",
-            "value": "404"
-          },
-          {
-            "comparison": "not_empty",
-            "source": "response_json",
-            "value": null,
-            "property": "detail"
-          },
-          {
-            "comparison": "equal",
-            "source": "response_json",
-            "value": "404",
-            "property": "status"
-          },
-          {
-            "comparison": "has_value",
-            "source": "response_json",
-            "value": "urn:ietf:params:scim:api:messages:2.0:Error",
-            "property": "schemas"
-          }
-        ],
-        "variables": [],
-        "scripts": [],
-        "before_scripts": []
-      }
-    ]
-  }
\ No newline at end of file
diff --git a/tests/test_litellm/test_github_triage_workflows.py b/tests/test_litellm/test_github_triage_workflows.py
index ec6e9fc2381..ef3ab8d25da 100644
--- a/tests/test_litellm/test_github_triage_workflows.py
+++ b/tests/test_litellm/test_github_triage_workflows.py
@@ -62,7 +62,6 @@ DESTRUCTIVE_GATE_ENV: dict[str, str] = {
 LLM_CLIENT_INSTALLER_WORKFLOWS = (
     "triage_issue_with_llm.yml",
     "triage_reconsider.yml",
-    "triage_rollout_heads_up.yml",
 )
 
 PINNED_INSTALL = "--require-hashes -r .github/scripts/triage-requirements.txt"
@@ -206,49 +205,6 @@ def test_triage_requirements_are_fully_hash_pinned() -> None:
         )
 
 
-def _heads_up_run_step() -> dict:
-    workflow = _load_workflow("triage_rollout_heads_up.yml")
-    for step in workflow["jobs"]["heads-up"]["steps"]:
-        if isinstance(step.get("run"), str) and "triage_rollout_heads_up.py" in step["run"]:
-            return step
-    raise AssertionError("no run step invokes triage_rollout_heads_up.py")
-
-
-def test_rollout_heads_up_push_trigger_never_posts() -> None:
-    """Merging the heads-up script to staging must stay inert: the automatic
-    push trigger only ever runs dry-run. The real one-shot sweep is a
-    deliberate manual `workflow_dispatch` with `dry_run=false`, the sole path
-    that adds `--close`.
-
-    This guards the "inert by default" invariant for the one workflow that is
-    intentionally not gated on AGENT_SHIN_ENABLED (it has to warn contributors
-    before that flag flips on). A regression to auto-`--close`-on-push would
-    post real comments on every push that touches the script.
-    """
-    run = _heads_up_run_step()["run"]
-    assert '"${GITHUB_EVENT_NAME:-}" = "workflow_dispatch"' in run, (
-        "the real (--close) run must be a manual workflow_dispatch, not the automatic push trigger"
-    )
-    assert '"${DRY_RUN_INPUT:-true}" = "false"' in run, (
-        "the real run must require the dry_run input to be the exact string 'false' (fail-safe); any other value stays dry-run"
-    )
-    assert run.count("ARGS+=(--close)") == 1, (
-        "--close must appear once, inside the manual real-run branch; a second occurrence means the push path posts real comments on merge"
-    )
-
-
-def test_rollout_heads_up_key_is_dispatch_gated() -> None:
-    """OPENAI_API_KEY is exposed only on the manual dispatch (the real-run
-    trigger), never unconditionally. The sibling triage workflows gate the key
-    the same way; an unconditional `secrets.OPENAI_API_KEY` here would hand the
-    key to the automatic push run, which must stay a no-op dry-run preview.
-    """
-    key_expr = (_heads_up_run_step().get("env") or {}).get("OPENAI_API_KEY", "")
-    assert "github.event_name == 'workflow_dispatch'" in key_expr, (
-        f"OPENAI_API_KEY must be gated on workflow_dispatch so the automatic push trigger gets no key; found: {key_expr!r}"
-    )
-
-
 def _reconsider_steps() -> list[dict]:
     workflow = _load_workflow("triage_reconsider.yml")
     return workflow["jobs"]["reconsider"]["steps"]
diff --git a/tests/test_litellm/test_triage_rollout_heads_up.py b/tests/test_litellm/test_triage_rollout_heads_up.py
deleted file mode 100644
index 535590fd2d6..00000000000
--- a/tests/test_litellm/test_triage_rollout_heads_up.py
+++ /dev/null
@@ -1,612 +0,0 @@
-"""Unit tests for the one-shot 7-day heads-up sweep.
-
-Exercises:
-
-  * The ``_agent_shin_actions`` dry-run wrappers — each ``maybe_*`` helper
-    must call the real underlying mutation iff ``dry_run=False``, and log to
-    stdout otherwise.
-  * ``triage_rollout_heads_up._would_be_closed`` — the predicate that
-    decides "would the future bot close this?" for both PRs and issues.
-  * ``triage_rollout_heads_up._process_one`` — the per-item processor:
-    skip when state != open, skip internal authors, skip already-notified
-    items, post heads-up on failing items, leave passing items alone.
-  * ``triage_rollout_heads_up.run`` — the sweep loop end-to-end, in both
-    dry-run and real modes, with the comment-posting injected so we never
-    talk to GitHub.
-
-Every test stubs out ``gh()`` and the GitHub mutations; nothing in this file
-ever shells out.
-"""
-
-from __future__ import annotations
-
-import datetime as dt
-import importlib.util
-import sys
-from pathlib import Path
-
-import pytest
-
-_SCRIPTS_DIR = Path(__file__).resolve().parents[2] / ".github" / "scripts"
-
-
-@pytest.fixture(scope="module")
-def triage_module():
-    """Load triage_with_llm under its canonical name so the sibling modules
-    can `from triage_with_llm import ...`."""
-    spec = importlib.util.spec_from_file_location(
-        "triage_with_llm", _SCRIPTS_DIR / "triage_with_llm.py"
-    )
-    assert spec and spec.loader
-    module = importlib.util.module_from_spec(spec)
-    sys.modules["triage_with_llm"] = module
-    spec.loader.exec_module(module)
-    return module
-
-
-@pytest.fixture(scope="module")
-def actions_module(triage_module):
-    spec = importlib.util.spec_from_file_location(
-        "_agent_shin_actions", _SCRIPTS_DIR / "_agent_shin_actions.py"
-    )
-    assert spec and spec.loader
-    module = importlib.util.module_from_spec(spec)
-    sys.modules["_agent_shin_actions"] = module
-    spec.loader.exec_module(module)
-    return module
-
-
-@pytest.fixture(scope="module")
-def heads_up_module(triage_module, actions_module):
-    spec = importlib.util.spec_from_file_location(
-        "triage_rollout_heads_up", _SCRIPTS_DIR / "triage_rollout_heads_up.py"
-    )
-    assert spec and spec.loader
-    module = importlib.util.module_from_spec(spec)
-    sys.modules["triage_rollout_heads_up"] = module
-    spec.loader.exec_module(module)
-    return module
-
-
-# ---------------------------------------------------------------------------
-# _agent_shin_actions: the dry-run wrappers
-
-
-class TestActionsDryRun:
-    """Each maybe_* helper must NOT hit GitHub in dry-run, and MUST hit it
-    in real mode. The whole rollout's safety story rests on this."""
-
-    def test_maybe_post_comment_dry_run_logs_only(
-        self, actions_module, triage_module, monkeypatch, capsys
-    ):
-        called = []
-        monkeypatch.setattr(
-            triage_module,
-            "post_comment",
-            lambda *a, **k: called.append((a, k)),
-        )
-        actions_module.maybe_post_comment("o/r", 7, "hello", dry_run=True)
-        assert called == []
-        assert "[DRY RUN] comment o/r#7" in capsys.readouterr().out
-
-    def test_maybe_post_comment_real_run_calls_through(
-        self, actions_module, triage_module, monkeypatch
-    ):
-        called = []
-        monkeypatch.setattr(
-            triage_module,
-            "post_comment",
-            lambda repo, n, body: called.append((repo, n, body)),
-        )
-        actions_module.maybe_post_comment("o/r", 7, "hello", dry_run=False)
-        assert called == [("o/r", 7, "hello")]
-
-
-# ---------------------------------------------------------------------------
-# _would_be_closed predicate
-
-
-class TestWouldBeClosed:
-    def test_pr_passing_returns_false(self, heads_up_module):
-        assert (
-            heads_up_module._would_be_closed(
-                "pr", {"passing": True, "action": "noop-passing"}
-            )
-            is False
-        )
-
-    def test_pr_failing_returns_true(self, heads_up_module):
-        assert (
-            heads_up_module._would_be_closed(
-                "pr",
-                {
-                    "passing": False,
-                    "action": "would-close",
-                    "verdict": {"verdict": "fail"},
-                },
-            )
-            is True
-        )
-
-    def test_pr_skipped_returns_false(self, heads_up_module):
-        # passing is None for skip paths (internal-author, llm-error, etc.)
-        assert (
-            heads_up_module._would_be_closed("pr", {"action": "skip-internal-author"})
-            is False
-        )
-
-    def test_issue_pass_returns_false(self, heads_up_module):
-        assert (
-            heads_up_module._would_be_closed(
-                "issue", {"action": "pass-llm", "verdict": {"verdict": "pass"}}
-            )
-            is False
-        )
-
-    def test_issue_fail_returns_true(self, heads_up_module):
-        assert (
-            heads_up_module._would_be_closed(
-                "issue", {"action": "would-close", "verdict": {"verdict": "fail"}}
-            )
-            is True
-        )
-
-    def test_issue_missing_verdict_returns_false(self, heads_up_module):
-        # Skip paths don't surface a verdict; treat as "won't close".
-        assert (
-            heads_up_module._would_be_closed("issue", {"action": "skip-not-open"})
-            is False
-        )
-
-
-# ---------------------------------------------------------------------------
-# Comment formatter — wording sanity checks
-
-
-class TestHeadsUpCommentBody:
-    def test_pr_comment_contains_cutoff_rubric_marker(self, heads_up_module):
-        body = heads_up_module.format_heads_up_comment(
-            kind="pr",
-            verdict={"verdict": "fail", "missing": ["QA proof"], "explanation": "thin"},
-            greptile_score=3,
-            cutoff=dt.date(2026, 6, 1),
-        )
-        assert "Monday, June 1, 2026" in body  # cutoff readable
-        assert "09:00 UTC" in body  # deadline is timezone-explicit
-        assert "we'll close it" in body  # hard deadline, not a passive notice
-        assert "2-hour lifetime" in body  # post-rollout steady state
-        assert "Greptile" in body and "3/5" in body  # specific shortfall
-        assert "QA proof" in body  # missing piece surfaced
-        assert "PR *description*" in body  # description-only note
-        assert heads_up_module.HEADS_UP_MARKER in body  # idempotency marker
-
-    def test_issue_comment_uses_reconsider_recovery_path(self, heads_up_module):
-        # OSS authors can't reopen an issue the bot closed (read access only
-        # lets them reopen issues they closed themselves), so the heads-up
-        # recovery path is `@agent-shin reconsider`, not self-reopen.
-        body = heads_up_module.format_heads_up_comment(
-            kind="issue",
-            verdict={"verdict": "fail", "missing": ["repro"], "explanation": ""},
-            greptile_score=None,
-            cutoff=dt.date(2026, 6, 1),
-        )
-        assert "@agent-shin reconsider" in body
-        assert heads_up_module.HEADS_UP_MARKER in body
-
-    def test_empty_missing_uses_fallback_copy(self, heads_up_module):
-        body = heads_up_module.format_heads_up_comment(
-            kind="pr",
-            verdict={"verdict": "fail", "missing": [], "explanation": ""},
-            greptile_score=None,
-            cutoff=dt.date(2026, 6, 1),
-        )
-        assert "couldn't articulate" in body
-        # Make sure the fallback didn't leave us with a broken sentence.
-        assert "specific missing piece" in body
-
-
-# ---------------------------------------------------------------------------
-# _process_one — per-item dispatch
-
-
-def _stub_fetchers(heads_up_module, triage_module, *, item):
-    """Monkeypatch fetch_pr and fetch_issue (both in triage_with_llm and the
-    re-imported names in heads_up_module) to return `item`."""
-    return [
-        (triage_module, "fetch_pr", lambda repo, n: item),
-        (triage_module, "fetch_issue", lambda repo, n: item),
-        (heads_up_module, "fetch_pr", lambda repo, n: item),
-        (heads_up_module, "fetch_issue", lambda repo, n: item),
-    ]
-
-
-class TestProcessOne:
-    """Per-item processing: the right skip reason fires for each scenario,
-    and the heads-up only goes out when the rubric is genuinely failing."""
-
-    @pytest.fixture
-    def patch_env(self, heads_up_module, triage_module, monkeypatch):
-        """Helper that returns a callable to install a PR/issue body, suppress
-        marker checks, and stub the comment poster."""
-        posts = []
-        monkeypatch.setattr(
-            heads_up_module,
-            "maybe_post_comment",
-            lambda repo, n, body, *, dry_run: posts.append((repo, n, body, dry_run)),
-        )
-        monkeypatch.setattr(heads_up_module, "_has_heads_up_marker", lambda item: False)
-        monkeypatch.setattr(
-            heads_up_module, "_comments_have_marker", lambda repo, n: False
-        )
-
-        def _install(item):
-            for mod, name, fn in _stub_fetchers(
-                heads_up_module, triage_module, item=item
-            ):
-                monkeypatch.setattr(mod, name, fn)
-
-        return _install, posts
-
-    def test_skip_closed_pr(self, heads_up_module, patch_env):
-        install, posts = patch_env
-        install(
-            {"state": "closed", "user": {"login": "ext"}, "author_association": "NONE"}
-        )
-        r = heads_up_module._process_one(
-            repo="o/r",
-            kind="pr",
-            number=7,
-            model="m",
-            cutoff=dt.date(2026, 6, 1),
-            dry_run=True,
-        )
-        assert r["action"] == "skip-not-open"
-        assert posts == []
-
-    def test_skip_internal_pr(self, heads_up_module, patch_env):
-        install, posts = patch_env
-        install(
-            {
-                "state": "open",
-                "user": {"login": "krrishdholakia"},
-                "author_association": "MEMBER",
-                "body": "",
-                "labels": [],
-                "created_at": "2026-05-25T00:00:00Z",
-            }
-        )
-        r = heads_up_module._process_one(
-            repo="o/r",
-            kind="pr",
-            number=7,
-            model="m",
-            cutoff=dt.date(2026, 6, 1),
-            dry_run=True,
-            allowlist=frozenset(),
-        )
-        assert r["action"] == "skip-internal-author"
-        assert posts == []
-
-    def test_skip_passing_pr(self, heads_up_module, patch_env, monkeypatch):
-        install, posts = patch_env
-        install(
-            {
-                "state": "open",
-                "user": {"login": "mateo-berri"},
-                "author_association": "NONE",
-                "body": "Fixes #123 — clean fix with a passing rubric.",
-                "labels": [],
-                "created_at": "2026-05-25T00:00:00Z",
-            }
-        )
-        monkeypatch.setattr(
-            heads_up_module,
-            "_evaluate_pr",
-            lambda **kwargs: {
-                "action": "noop-passing",
-                "passing": True,
-                "verdict": {"verdict": "pass"},
-                "greptile_score": 5,
-            },
-        )
-        r = heads_up_module._process_one(
-            repo="o/r",
-            kind="pr",
-            number=7,
-            model="m",
-            cutoff=dt.date(2026, 6, 1),
-            dry_run=True,
-        )
-        assert r["action"] == "skip-passing"
-        assert posts == []
-
-    def test_failing_pr_posts_heads_up_dry_run(
-        self, heads_up_module, patch_env, monkeypatch, capsys
-    ):
-        install, posts = patch_env
-        install(
-            {
-                "state": "open",
-                "user": {"login": "mateo-berri"},
-                "author_association": "NONE",
-                "body": "thin",
-                "labels": [],
-                "created_at": "2026-05-25T00:00:00Z",
-            }
-        )
-        monkeypatch.setattr(
-            heads_up_module,
-            "_evaluate_pr",
-            lambda **kwargs: {
-                "action": "would-close",
-                "passing": False,
-                "verdict": {
-                    "verdict": "fail",
-                    "missing": ["QA proof"],
-                    "explanation": "PR body is one line.",
-                },
-                "greptile_score": 3,
-            },
-        )
-        r = heads_up_module._process_one(
-            repo="o/r",
-            kind="pr",
-            number=7,
-            model="m",
-            cutoff=dt.date(2026, 6, 1),
-            dry_run=True,
-        )
-        assert r["action"] == "would-post-heads-up"
-        assert posts == [("o/r", 7, posts[0][2], True)]  # tuple shape preserved
-        assert "QA proof" in posts[0][2]
-        assert heads_up_module.HEADS_UP_MARKER in posts[0][2]
-
-    def test_failing_issue_posts_heads_up_real_run(
-        self, heads_up_module, patch_env, monkeypatch
-    ):
-        install, posts = patch_env
-        install(
-            {
-                "state": "open",
-                "user": {"login": "mateo-berri"},
-                "author_association": "NONE",
-                "body": "X is broken",
-                "labels": [],
-                "created_at": "2026-05-25T00:00:00Z",
-            }
-        )
-        monkeypatch.setattr(
-            heads_up_module,
-            "_evaluate_issue",
-            lambda **kwargs: {
-                "action": "would-close",
-                "verdict": {
-                    "verdict": "fail",
-                    "missing": ["reproduction"],
-                    "explanation": "too thin",
-                },
-            },
-        )
-        r = heads_up_module._process_one(
-            repo="o/r",
-            kind="issue",
-            number=42,
-            model="m",
-            cutoff=dt.date(2026, 6, 1),
-            dry_run=False,
-        )
-        assert r["action"] == "heads-up-posted"
-        assert len(posts) == 1
-        _, n, _, dry = posts[0]
-        assert n == 42 and dry is False
-
-    def test_already_notified_is_skipped(self, heads_up_module, patch_env, monkeypatch):
-        install, posts = patch_env
-        install(
-            {
-                "state": "open",
-                "user": {"login": "mateo-berri"},
-                "author_association": "NONE",
-                "body": "thin",
-                "labels": [],
-                "created_at": "2026-05-25T00:00:00Z",
-            }
-        )
-        # Override the marker check for this scenario only.
-        monkeypatch.setattr(
-            heads_up_module, "_comments_have_marker", lambda repo, n: True
-        )
-        r = heads_up_module._process_one(
-            repo="o/r",
-            kind="pr",
-            number=7,
-            model="m",
-            cutoff=dt.date(2026, 6, 1),
-            dry_run=True,
-        )
-        assert r["action"] == "skip-already-notified"
-        assert posts == []
-
-    def test_ignore_existing_marker_forces_post(
-        self, heads_up_module, patch_env, monkeypatch
-    ):
-        install, posts = patch_env
-        install(
-            {
-                "state": "open",
-                "user": {"login": "mateo-berri"},
-                "author_association": "NONE",
-                "body": "thin",
-                "labels": [],
-                "created_at": "2026-05-25T00:00:00Z",
-            }
-        )
-        monkeypatch.setattr(
-            heads_up_module, "_comments_have_marker", lambda repo, n: True
-        )
-        monkeypatch.setattr(
-            heads_up_module,
-            "_evaluate_pr",
-            lambda **kwargs: {
-                "action": "would-close",
-                "passing": False,
-                "verdict": {"verdict": "fail", "missing": ["X"], "explanation": ""},
-                "greptile_score": None,
-            },
-        )
-        r = heads_up_module._process_one(
-            repo="o/r",
-            kind="pr",
-            number=7,
-            model="m",
-            cutoff=dt.date(2026, 6, 1),
-            dry_run=True,
-            skip_marker_check=True,
-        )
-        assert r["action"] == "would-post-heads-up"
-
-
-# ---------------------------------------------------------------------------
-# run() — sweep loop
-
-
-class TestRun:
-    """End-to-end the sweep loop with a tiny fake repo: 1 passing PR, 1
-    failing PR, 1 passing issue, 1 failing issue."""
-
-    @pytest.fixture
-    def configured(self, heads_up_module, triage_module, monkeypatch):
-        posts = []
-        monkeypatch.setattr(
-            heads_up_module,
-            "maybe_post_comment",
-            lambda repo, n, body, *, dry_run: posts.append((n, dry_run, body)),
-        )
-        monkeypatch.setattr(heads_up_module, "_has_heads_up_marker", lambda item: False)
-        monkeypatch.setattr(
-            heads_up_module, "_comments_have_marker", lambda repo, n: False
-        )
-
-        def fake_list(repo, kind):
-            return [1, 2] if kind == "pr" else [101, 102]
-
-        monkeypatch.setattr(heads_up_module, "_list_open_numbers", fake_list)
-
-        def make_item(login="mateo-berri"):
-            return {
-                "state": "open",
-                "user": {"login": login},
-                "author_association": "NONE",
-                "body": "thin",
-                "labels": [],
-                "created_at": "2026-05-25T00:00:00Z",
-            }
-
-        monkeypatch.setattr(heads_up_module, "fetch_pr", lambda repo, n: make_item())
-        monkeypatch.setattr(heads_up_module, "fetch_issue", lambda repo, n: make_item())
-        monkeypatch.setattr(triage_module, "fetch_pr", lambda repo, n: make_item())
-        monkeypatch.setattr(triage_module, "fetch_issue", lambda repo, n: make_item())
-
-        def pr_eval(*, number, **kwargs):
-            if number == 1:
-                return {
-                    "action": "noop-passing",
-                    "passing": True,
-                    "verdict": {"verdict": "pass"},
-                }
-            return {
-                "action": "would-close",
-                "passing": False,
-                "verdict": {"verdict": "fail", "missing": ["m"], "explanation": ""},
-                "greptile_score": 2,
-            }
-
-        def issue_eval(*, number, **kwargs):
-            if number == 101:
-                return {"action": "pass-llm", "verdict": {"verdict": "pass"}}
-            return {
-                "action": "would-close",
-                "verdict": {"verdict": "fail", "missing": ["repro"], "explanation": ""},
-            }
-
-        monkeypatch.setattr(heads_up_module, "_evaluate_pr", pr_eval)
-        monkeypatch.setattr(heads_up_module, "_evaluate_issue", issue_eval)
-        return posts
-
-    def test_dry_run_posts_nothing_but_logs_both_would_posts(
-        self, heads_up_module, configured, capsys
-    ):
-        results = heads_up_module.run(
-            repo="o/r",
-            close=False,
-            cutoff=dt.date(2026, 6, 1),
-            model="m",
-        )
-        actions = [r["action"] for r in results]
-        assert actions.count("would-post-heads-up") == 2
-        assert actions.count("skip-passing") == 2
-        assert all(dry for _, dry, _ in configured)  # every post was dry-run
-
-    def test_real_run_posts_two_comments(self, heads_up_module, configured):
-        results = heads_up_module.run(
-            repo="o/r",
-            close=True,
-            cutoff=dt.date(2026, 6, 1),
-            model="m",
-        )
-        assert sum(1 for r in results if r["action"] == "heads-up-posted") == 2
-        # Two real-run posts: one failing PR (#2), one failing issue (#102).
-        real_posts = [n for n, dry, _ in configured if dry is False]
-        assert sorted(real_posts) == [2, 102]
-
-    def test_kinds_filter_skips_issues(self, heads_up_module, configured):
-        results = heads_up_module.run(
-            repo="o/r",
-            close=False,
-            cutoff=dt.date(2026, 6, 1),
-            model="m",
-            kinds=("pr",),
-        )
-        assert {r["kind"] for r in results} == {"pr"}
-
-    def test_only_numbers_restricts_sweep(self, heads_up_module, configured):
-        results = heads_up_module.run(
-            repo="o/r",
-            close=False,
-            cutoff=dt.date(2026, 6, 1),
-            model="m",
-            only_numbers={"pr": [2], "issue": [101]},
-        )
-        assert sorted((r["kind"], r["number"]) for r in results) == [
-            ("issue", 101),
-            ("pr", 2),
-        ]
-
-
-class TestListOpenNumbersNoCap:
-    """`_list_open_numbers` must sweep the WHOLE backlog, not a capped page.
-
-    Regression guard: the rollout sweep is one-shot, so any item it misses
-    here never gets a heads-up before the bot starts auto-closing.
-    """
-
-    def test_delegates_to_list_open_items_with_no_cap(
-        self, heads_up_module, monkeypatch
-    ):
-        import agent_shin_shared
-
-        captured: dict = {}
-
-        def fake_gh(*args):
-            captured["args"] = args
-            return '[{"number": 5}, {"number": 9}]'
-
-        monkeypatch.setattr(agent_shin_shared, "gh", fake_gh)
-        numbers = heads_up_module._list_open_numbers("o/r", "issue")
-        assert numbers == [5, 9]
-        args = captured["args"]
-        assert args[0] == "issue"
-        assert args[args.index("--limit") + 1] == str(
-            agent_shin_shared.GH_LIST_ALL_LIMIT
-        )
-        assert "1000" not in args

From 7de8f458e0df75327090be49b9e7639963f98732 Mon Sep 17 00:00:00 2001
From: yuneng-jiang <yuneng@berri.ai>
Date: Thu, 20 Aug 2026 10:08:28 -0700
Subject: [PATCH 31/35] test: retire tests/old_proxy_tests, which holds no
 tests (#37605)

* test: retire tests/old_proxy_tests, which holds no tests

Twenty files named test_*.py, and pytest collects nothing from any of them:

  uv run pytest tests/old_proxy_tests --collect-only -q
  no tests collected, 16 errors in 114.17s

They are manual snippets against a running proxy, written at module level with
no test function, no assertion and no entry point, so the only thing the name
buys them is a place on the coverage allowlist. Sixteen of the twenty cannot
even be imported in this environment, wanting langchain, llama_index or
google.api_core, and ten still point at 0.0.0.0:8000, which stopped being the
proxy's default port some time ago.

Nothing outside the directory refers to it apart from the allowlist entry, which
goes with it. The other loose contents go too: five load_test_*.py scripts, a
bursty variant, two committed log files, an essay fixture and a stray .js
snippet.

Allowlist paths 88 -> 68, test files 2422 -> 2402, and no job loses anything it
was running. Recoverable from history if a snippet turns out to be someone's
habit.

* test: drop the retired old_proxy_tests paths from the coverage allowlist
---
 .github/ci-coverage-allowlist.yml             |  24 --
 .../tests/bursty_load_test_completion.py      |  50 ---
 tests/old_proxy_tests/tests/error_log.txt     |   0
 tests/old_proxy_tests/tests/large_text.py     | 112 ------
 .../tests/llama_index_data/essay.txt          | 353 ------------------
 .../tests/load_test_completion.py             |  68 ----
 .../tests/load_test_embedding.py              | 107 ------
 .../tests/load_test_embedding_100.py          |  54 ---
 .../tests/load_test_embedding_proxy.py        | 107 ------
 tests/old_proxy_tests/tests/load_test_q.py    | 121 ------
 tests/old_proxy_tests/tests/request_log.txt   |   0
 .../tests/test_anthropic_context_caching.py   |  36 --
 .../tests/test_anthropic_sdk.py               |  22 --
 tests/old_proxy_tests/tests/test_async.py     |  28 --
 .../tests/test_gemini_context_caching.py      |  54 ---
 .../tests/test_langchain_embedding.py         |  17 -
 .../tests/test_langchain_request.py           |  44 ---
 .../old_proxy_tests/tests/test_llamaindex.py  |  36 --
 .../old_proxy_tests/tests/test_mistral_sdk.py |  13 -
 .../tests/test_openai_embedding.py            | 126 -------
 .../tests/test_openai_exception_request.py    |  53 ---
 tests/old_proxy_tests/tests/test_openai_js.js |  41 --
 .../tests/test_openai_request.py              |  60 ---
 .../test_openai_request_with_traceparent.py   |  41 --
 .../tests/test_openai_simple_embedding.py     |  10 -
 .../tests/test_openai_tts_request.py          |  11 -
 .../tests/test_pass_through_langfuse.py       |  14 -
 tests/old_proxy_tests/tests/test_q.py         |  85 -----
 .../tests/test_simple_traceparent_openai.py   |  22 --
 .../tests/test_vertex_sdk_forward_headers.py  |  52 ---
 .../tests/test_vtx_embedding.py               |  21 --
 .../tests/test_vtx_sdk_embedding.py           |  58 ---
 32 files changed, 1840 deletions(-)
 delete mode 100644 tests/old_proxy_tests/tests/bursty_load_test_completion.py
 delete mode 100644 tests/old_proxy_tests/tests/error_log.txt
 delete mode 100644 tests/old_proxy_tests/tests/large_text.py
 delete mode 100644 tests/old_proxy_tests/tests/llama_index_data/essay.txt
 delete mode 100644 tests/old_proxy_tests/tests/load_test_completion.py
 delete mode 100644 tests/old_proxy_tests/tests/load_test_embedding.py
 delete mode 100644 tests/old_proxy_tests/tests/load_test_embedding_100.py
 delete mode 100644 tests/old_proxy_tests/tests/load_test_embedding_proxy.py
 delete mode 100644 tests/old_proxy_tests/tests/load_test_q.py
 delete mode 100644 tests/old_proxy_tests/tests/request_log.txt
 delete mode 100644 tests/old_proxy_tests/tests/test_anthropic_context_caching.py
 delete mode 100644 tests/old_proxy_tests/tests/test_anthropic_sdk.py
 delete mode 100644 tests/old_proxy_tests/tests/test_async.py
 delete mode 100644 tests/old_proxy_tests/tests/test_gemini_context_caching.py
 delete mode 100644 tests/old_proxy_tests/tests/test_langchain_embedding.py
 delete mode 100644 tests/old_proxy_tests/tests/test_langchain_request.py
 delete mode 100644 tests/old_proxy_tests/tests/test_llamaindex.py
 delete mode 100644 tests/old_proxy_tests/tests/test_mistral_sdk.py
 delete mode 100644 tests/old_proxy_tests/tests/test_openai_embedding.py
 delete mode 100644 tests/old_proxy_tests/tests/test_openai_exception_request.py
 delete mode 100644 tests/old_proxy_tests/tests/test_openai_js.js
 delete mode 100644 tests/old_proxy_tests/tests/test_openai_request.py
 delete mode 100644 tests/old_proxy_tests/tests/test_openai_request_with_traceparent.py
 delete mode 100644 tests/old_proxy_tests/tests/test_openai_simple_embedding.py
 delete mode 100644 tests/old_proxy_tests/tests/test_openai_tts_request.py
 delete mode 100644 tests/old_proxy_tests/tests/test_pass_through_langfuse.py
 delete mode 100644 tests/old_proxy_tests/tests/test_q.py
 delete mode 100644 tests/old_proxy_tests/tests/test_simple_traceparent_openai.py
 delete mode 100644 tests/old_proxy_tests/tests/test_vertex_sdk_forward_headers.py
 delete mode 100644 tests/old_proxy_tests/tests/test_vtx_embedding.py
 delete mode 100644 tests/old_proxy_tests/tests/test_vtx_sdk_embedding.py

diff --git a/.github/ci-coverage-allowlist.yml b/.github/ci-coverage-allowlist.yml
index ccc21512e79..ae24bee3113 100644
--- a/.github/ci-coverage-allowlist.yml
+++ b/.github/ci-coverage-allowlist.yml
@@ -63,30 +63,6 @@ test_paths:
       - tests/litellm/test_router_retry_backoff_headers.py
       - tests/litellm/test_sambanova_model_metadata.py
       - tests/litellm/test_stream_chunk_builder_images.py
-  - reason: >-
-      Legacy proxy suite superseded by the proxy shards; no job invokes it and whether it still
-      describes supported behaviour is unresolved
-    paths:
-      - tests/old_proxy_tests/tests/test_anthropic_context_caching.py
-      - tests/old_proxy_tests/tests/test_anthropic_sdk.py
-      - tests/old_proxy_tests/tests/test_async.py
-      - tests/old_proxy_tests/tests/test_gemini_context_caching.py
-      - tests/old_proxy_tests/tests/test_langchain_embedding.py
-      - tests/old_proxy_tests/tests/test_langchain_request.py
-      - tests/old_proxy_tests/tests/test_llamaindex.py
-      - tests/old_proxy_tests/tests/test_mistral_sdk.py
-      - tests/old_proxy_tests/tests/test_openai_embedding.py
-      - tests/old_proxy_tests/tests/test_openai_exception_request.py
-      - tests/old_proxy_tests/tests/test_openai_request.py
-      - tests/old_proxy_tests/tests/test_openai_request_with_traceparent.py
-      - tests/old_proxy_tests/tests/test_openai_simple_embedding.py
-      - tests/old_proxy_tests/tests/test_openai_tts_request.py
-      - tests/old_proxy_tests/tests/test_pass_through_langfuse.py
-      - tests/old_proxy_tests/tests/test_q.py
-      - tests/old_proxy_tests/tests/test_simple_traceparent_openai.py
-      - tests/old_proxy_tests/tests/test_vertex_sdk_forward_headers.py
-      - tests/old_proxy_tests/tests/test_vtx_embedding.py
-      - tests/old_proxy_tests/tests/test_vtx_sdk_embedding.py
   - reason: >-
       No job invokes this suite and its files mix pure transformation tests with ones driving live
       vendor vector stores, so assigning them needs a per-file decision
diff --git a/tests/old_proxy_tests/tests/bursty_load_test_completion.py b/tests/old_proxy_tests/tests/bursty_load_test_completion.py
deleted file mode 100644
index 642bd9f14d4..00000000000
--- a/tests/old_proxy_tests/tests/bursty_load_test_completion.py
+++ /dev/null
@@ -1,50 +0,0 @@
-import time, asyncio
-from openai import AsyncOpenAI
-from litellm._uuid import uuid
-import traceback
-
-
-litellm_client = AsyncOpenAI(api_key="test", base_url="http://0.0.0.0:8000")
-
-
-async def litellm_completion():
-    # Your existing code for litellm_completion goes here
-    try:
-        response = await litellm_client.chat.completions.create(
-            model="gpt-3.5-turbo",
-            messages=[
-                {"role": "user", "content": f"This is a test: {uuid.uuid4()}" * 180}
-            ],  # this is about 4k tokens per request
-        )
-        return response
-
-    except Exception as e:
-        # If there's an exception, log the error message
-        with open("error_log.txt", "a") as error_log:
-            error_log.write(f"Error during completion: {str(e)}\n")
-        pass
-
-
-async def main():
-    start = time.time()
-    n = 60  # Send 60 concurrent requests, each with 4k tokens = 240k Tokens
-    tasks = [litellm_completion() for _ in range(n)]
-
-    chat_completions = await asyncio.gather(*tasks)
-
-    successful_completions = [c for c in chat_completions if c is not None]
-
-    # Write errors to error_log.txt
-    with open("error_log.txt", "a") as error_log:
-        for completion in chat_completions:
-            if isinstance(completion, str):
-                error_log.write(completion + "\n")
-
-    print(n, time.time() - start, len(successful_completions))
-
-
-if __name__ == "__main__":
-    # Blank out contents of error_log.txt
-    open("error_log.txt", "w").close()
-
-    asyncio.run(main())
diff --git a/tests/old_proxy_tests/tests/error_log.txt b/tests/old_proxy_tests/tests/error_log.txt
deleted file mode 100644
index e69de29bb2d..00000000000
diff --git a/tests/old_proxy_tests/tests/large_text.py b/tests/old_proxy_tests/tests/large_text.py
deleted file mode 100644
index 86904a6d148..00000000000
--- a/tests/old_proxy_tests/tests/large_text.py
+++ /dev/null
@@ -1,112 +0,0 @@
-text = """
-Alexander the Great
-This article is about the ancient king of Macedonia. For other uses, see Alexander the Great (disambiguation).
-Alexander III of Macedon (Ancient Greek: Ἀλέξανδρος, romanized: Alexandros; 20/21 July 356 BC – 10/11 June 323 BC), most commonly known as Alexander the Great,[c] was a king of the ancient Greek kingdom of Macedon.[d] He succeeded his father Philip II to the throne in 336 BC at the age of 20 and spent most of his ruling years conducting a lengthy military campaign throughout Western Asia, Central Asia, parts of South Asia, and Egypt. By the age of 30, he had created one of the largest empires in history, stretching from Greece to northwestern India.[1] He was undefeated in battle and is widely considered to be one of history's greatest and most successful military commanders.[2][3]
-
-Until the age of 16, Alexander was tutored by Aristotle. In 335 BC, shortly after his assumption of kingship over Macedon, he campaigned in the Balkans and reasserted control over Thrace and parts of Illyria before marching on the city of Thebes, which was subsequently destroyed in battle. Alexander then led the League of Corinth, and used his authority to launch the pan-Hellenic project envisaged by his father, assuming leadership over all Greeks in their conquest of Persia.[4][5]
-
-In 334 BC, he invaded the Achaemenid Persian Empire and began a series of campaigns that lasted for 10 years. Following his conquest of Asia Minor, Alexander broke the power of Achaemenid Persia in a series of decisive battles, including those at Issus and Gaugamela; he subsequently overthrew Darius III and conquered the Achaemenid Empire in its entirety.[e] After the fall of Persia, the Macedonian Empire held a vast swath of territory between the Adriatic Sea and the Indus River. Alexander endeavored to reach the "ends of the world and the Great Outer Sea" and invaded India in 326 BC, achieving an important victory over Porus, an ancient Indian king of present-day Punjab, at the Battle of the Hydaspes. Due to the demand of his homesick troops, he eventually turned back at the Beas River and later died in 323 BC in Babylon, the city of Mesopotamia that he had planned to establish as his empire's capital. Alexander's death left unexecuted an additional series of planned military and mercantile campaigns that would have begun with a Greek invasion of Arabia. In the years following his death, a series of civil wars broke out across the Macedonian Empire, eventually leading to its disintegration at the hands of the Diadochi.
-
-With his death marking the start of the Hellenistic period, Alexander's legacy includes the cultural diffusion and syncretism that his conquests engendered, such as Greco-Buddhism and Hellenistic Judaism. He founded more than twenty cities, with the most prominent being the city of Alexandria in Egypt. Alexander's settlement of Greek colonists and the resulting spread of Greek culture led to the overwhelming dominance of Hellenistic civilization and influence as far east as the Indian subcontinent. The Hellenistic period developed through the Roman Empire into modern Western culture; the Greek language became the lingua franca of the region and was the predominant language of the Byzantine Empire up until its collapse in the mid-15th century AD. Alexander became legendary as a classical hero in the mould of Achilles, featuring prominently in the historical and mythical traditions of both Greek and non-Greek cultures. His military achievements and unprecedented enduring successes in battle made him the measure against which many later military leaders would compare themselves,[f] and his tactics remain a significant subject of study in military academies worldwide.[6] Legends of Alexander's exploits coalesced into the third-century Alexander Romance which, in the premodern period, went through over one hundred recensions, translations, and derivations and was translated into almost every European vernacular and every language of the Islamic world.[7] After the Bible, it was the most popular form of European literature.[8]
-
-Early life
-
-Lineage and childhood
-
-Alexander III was born in Pella, the capital of the Kingdom of Macedon,[9] on the sixth day of the ancient Greek month of Hekatombaion, which probably corresponds to 20 July 356 BC (although the exact date is uncertain).[10][11] He was the son of the erstwhile king of Macedon, Philip II, and his fourth wife, Olympias (daughter of Neoptolemus I, king of Epirus).[12][g] Although Philip had seven or eight wives, Olympias was his principal wife for some time, likely because she gave birth to Alexander.[13]
-
-Several legends surround Alexander's birth and childhood.[14] According to the ancient Greek biographer Plutarch, on the eve of the consummation of her marriage to Philip, Olympias dreamed that her womb was struck by a thunderbolt that caused a flame to spread "far and wide" before dying away. Sometime after the wedding, Philip is said to have seen himself, in a dream, securing his wife's womb with a seal engraved with a lion's image.[15] Plutarch offered a variety of interpretations for these dreams: that Olympias was pregnant before her marriage, indicated by the sealing of her womb; or that Alexander's father was Zeus. Ancient commentators were divided about whether the ambitious Olympias promulgated the story of Alexander's divine parentage, variously claiming that she had told Alexander, or that she dismissed the suggestion as impious.[15]
-
-On the day Alexander was born, Philip was preparing a siege on the city of Potidea on the peninsula of Chalcidice. That same day, Philip received news that his general Parmenion had defeated the combined Illyrian and Paeonian armies and that his horses had won at the Olympic Games. It was also said that on this day, the Temple of Artemis in Ephesus, one of the Seven Wonders of the World, burnt down. This led Hegesias of Magnesia to say that it had burnt down because Artemis was away, attending the birth of Alexander.[16] Such legends may have emerged when Alexander was king, and possibly at his instigation, to show that he was superhuman and destined for greatness from conception.[14]
-
-In his early years, Alexander was raised by a nurse, Lanike, sister of Alexander's future general Cleitus the Black. Later in his childhood, Alexander was tutored by the strict Leonidas, a relative of his mother, and by Lysimachus of Acarnania.[17] Alexander was raised in the manner of noble Macedonian youths, learning to read, play the lyre, ride, fight, and hunt.[18] When Alexander was ten years old, a trader from Thessaly brought Philip a horse, which he offered to sell for thirteen talents. The horse refused to be mounted, and Philip ordered it away. Alexander, however, detecting the horse's fear of its own shadow, asked to tame the horse, which he eventually managed.[14] Plutarch stated that Philip, overjoyed at this display of courage and ambition, kissed his son tearfully, declaring: "My boy, you must find a kingdom big enough for your ambitions. Macedon is too small for you", and bought the horse for him.[19] Alexander named it Bucephalas, meaning "ox-head". Bucephalas carried Alexander as far as India. When the animal died (because of old age, according to Plutarch, at age 30), Alexander named a city after him, Bucephala.[20]
-
-Education
-
-When Alexander was 13, Philip began to search for a tutor, and considered such academics as Isocrates and Speusippus, the latter offering to resign from his stewardship of the Academy to take up the post. In the end, Philip chose Aristotle and provided the Temple of the Nymphs at Mieza as a classroom. In return for teaching Alexander, Philip agreed to rebuild Aristotle's hometown of Stageira, which Philip had razed, and to repopulate it by buying and freeing the ex-citizens who were slaves, or pardoning those who were in exile.[21]
-
-Mieza was like a boarding school for Alexander and the children of Macedonian nobles, such as Ptolemy, Hephaistion, and Cassander. Many of these students would become his friends and future generals, and are often known as the "Companions". Aristotle taught Alexander and his companions about medicine, philosophy, morals, religion, logic, and art. Under Aristotle's tutelage, Alexander developed a passion for the works of Homer, and in particular the Iliad; Aristotle gave him an annotated copy, which Alexander later carried on his campaigns.[22] Alexander was able to quote Euripides from memory.[23]
-
-During his youth, Alexander was also acquainted with Persian exiles at the Macedonian court, who received the protection of Philip II for several years as they opposed Artaxerxes III.[24][25][26] Among them were Artabazos II and his daughter Barsine, possible future mistress of Alexander, who resided at the Macedonian court from 352 to 342 BC, as well as Amminapes, future satrap of Alexander, or a Persian nobleman named Sisines.[24][27][28][29] This gave the Macedonian court a good knowledge of Persian issues, and may even have influenced some of the innovations in the management of the Macedonian state.[27]
-
-Suda writes that Anaximenes of Lampsacus was one of Alexander's teachers, and that Anaximenes also accompanied Alexander on his campaigns.[30]
-
-Heir of Philip II
-
-Regency and ascent of Macedon
-
-Main articles: Philip II of Macedon and Rise of Macedon
-Further information: History of Macedonia (ancient kingdom)
-At the age of 16, Alexander's education under Aristotle ended. Philip II had waged war against the Thracians to the north, which left Alexander in charge as regent and heir apparent.[14] During Philip's absence, the Thracian tribe of Maedi revolted against Macedonia. Alexander responded quickly and drove them from their territory. The territory was colonized, and a city, named Alexandropolis, was founded.[31]
-
-Upon Philip's return, Alexander was dispatched with a small force to subdue the revolts in southern Thrace. Campaigning against the Greek city of Perinthus, Alexander reportedly saved his father's life. Meanwhile, the city of Amphissa began to work lands that were sacred to Apollo near Delphi, a sacrilege that gave Philip the opportunity to further intervene in Greek affairs. While Philip was occupied in Thrace, Alexander was ordered to muster an army for a campaign in southern Greece. Concerned that other Greek states might intervene, Alexander made it look as though he was preparing to attack Illyria instead. During this turmoil, the Illyrians invaded Macedonia, only to be repelled by Alexander.[32]
-
-Philip and his army joined his son in 338 BC, and they marched south through Thermopylae, taking it after stubborn resistance from its Theban garrison. They went on to occupy the city of Elatea, only a few days' march from both Athens and Thebes. The Athenians, led by Demosthenes, voted to seek alliance with Thebes against Macedonia. Both Athens and Philip sent embassies to win Thebes's favour, but Athens won the contest.[33] Philip marched on Amphissa (ostensibly acting on the request of the Amphictyonic League), capturing the mercenaries sent there by Demosthenes and accepting the city's surrender. Philip then returned to Elatea, sending a final offer of peace to Athens and Thebes, who both rejected it.[34]
-
-As Philip marched south, his opponents blocked him near Chaeronea, Boeotia. During the ensuing Battle of Chaeronea, Philip commanded the right wing and Alexander the left, accompanied by a group of Philip's trusted generals. According to the ancient sources, the two sides fought bitterly for some time. Philip deliberately commanded his troops to retreat, counting on the untested Athenian hoplites to follow, thus breaking their line. Alexander was the first to break the Theban lines, followed by Philip's generals. Having damaged the enemy's cohesion, Philip ordered his troops to press forward and quickly routed them. With the Athenians lost, the Thebans were surrounded. Left to fight alone, they were defeated.[35]
-
-After the victory at Chaeronea, Philip and Alexander marched unopposed into the Peloponnese, welcomed by all cities; however, when they reached Sparta, they were refused, but did not resort to war.[36] At Corinth, Philip established a "Hellenic Alliance" (modelled on the old anti-Persian alliance of the Greco-Persian Wars), which included most Greek city-states except Sparta. Philip was then named Hegemon (often translated as "Supreme Commander") of this league (known by modern scholars as the League of Corinth), and announced his plans to attack the Persian Empire.[37][38]
-
-Exile and return
-
-When Philip returned to Pella, he fell in love with and married Cleopatra Eurydice in 338 BC,[39] the niece of his general Attalus.[40] The marriage made Alexander's position as heir less secure, since any son of Cleopatra Eurydice would be a fully Macedonian heir, while Alexander was only half-Macedonian.[41] During the wedding banquet, a drunken Attalus publicly prayed to the gods that the union would produce a legitimate heir.[40]
-
-At the wedding of Cleopatra, whom Philip fell in love with and married, she being much too young for him, her uncle Attalus in his drink desired the Macedonians would implore the gods to give them a lawful successor to the kingdom by his niece. This so irritated Alexander, that throwing one of the cups at his head, "You villain," said he, "what, am I then a bastard?" Then Philip, taking Attalus's part, rose up and would have run his son through; but by good fortune for them both, either his over-hasty rage, or the wine he had drunk, made his foot slip, so that he fell down on the floor. At which Alexander reproachfully insulted over him: "See there," said he, "the man who makes preparations to pass out of Europe into Asia, overturned in passing from one seat to another."
-
-— Plutarch, describing the feud at Philip's wedding.[42]none
-In 337 BC, Alexander fled Macedon with his mother, dropping her off with her brother, King Alexander I of Epirus in Dodona, capital of the Molossians.[43] He continued to Illyria,[43] where he sought refuge with one or more Illyrian kings, perhaps with Glaucias, and was treated as a guest, despite having defeated them in battle a few years before.[44] However, it appears Philip never intended to disown his politically and militarily trained son.[43] Accordingly, Alexander returned to Macedon after six months due to the efforts of a family friend, Demaratus, who mediated between the two parties.[45]
-
-In the following year, the Persian satrap (governor) of Caria, Pixodarus, offered his eldest daughter to Alexander's half-brother, Philip Arrhidaeus.[43] Olympias and several of Alexander's friends suggested this showed Philip intended to make Arrhidaeus his heir.[43] Alexander reacted by sending an actor, Thessalus of Corinth, to tell Pixodarus that he should not offer his daughter's hand to an illegitimate son, but instead to Alexander. When Philip heard of this, he stopped the negotiations and scolded Alexander for wishing to marry the daughter of a Carian, explaining that he wanted a better bride for him.[43] Philip exiled four of Alexander's friends, Harpalus, Nearchus, Ptolemy and Erigyius, and had the Corinthians bring Thessalus to him in chains.[46]
-
-King of Macedon
-
-Accession
-
-Further information: Government of Macedonia (ancient kingdom)
-In summer 336 BC, while at Aegae attending the wedding of his daughter Cleopatra to Olympias's brother, Alexander I of Epirus, Philip was assassinated by the captain of his bodyguards, Pausanias.[h] As Pausanias tried to escape, he tripped over a vine and was killed by his pursuers, including two of Alexander's companions, Perdiccas and Leonnatus. Alexander was proclaimed king on the spot by the nobles and army at the age of 20.[47][48][49]
-
-Consolidation of power
-
-Alexander began his reign by eliminating potential rivals to the throne. He had his cousin, the former Amyntas IV, executed.[51] He also had two Macedonian princes from the region of Lyncestis killed for having been involved in his father's assassination, but spared a third, Alexander Lyncestes. Olympias had Cleopatra Eurydice, and Europa, her daughter by Philip, burned alive. When Alexander learned about this, he was furious. Alexander also ordered the murder of Attalus,[51] who was in command of the advance guard of the army in Asia Minor and Cleopatra's uncle.[52]
-
-Attalus was at that time corresponding with Demosthenes, regarding the possibility of defecting to Athens. Attalus also had severely insulted Alexander, and following Cleopatra's murder, Alexander may have considered him too dangerous to be left alive.[52] Alexander spared Arrhidaeus, who was by all accounts mentally disabled, possibly as a result of poisoning by Olympias.[47][49][53]
-
-News of Philip's death roused many states into revolt, including Thebes, Athens, Thessaly, and the Thracian tribes north of Macedon. When news of the revolts reached Alexander, he responded quickly. Though advised to use diplomacy, Alexander mustered 3,000 Macedonian cavalry and rode south towards Thessaly. He found the Thessalian army occupying the pass between Mount Olympus and Mount Ossa, and ordered his men to ride over Mount Ossa. When the Thessalians awoke the next day, they found Alexander in their rear and promptly surrendered, adding their cavalry to Alexander's force. He then continued south towards the Peloponnese.[54]
-
-Alexander stopped at Thermopylae, where he was recognized as the leader of the Amphictyonic League before heading south to Corinth. Athens sued for peace and Alexander pardoned the rebels. The famous encounter between Alexander and Diogenes the Cynic occurred during Alexander's stay in Corinth. When Alexander asked Diogenes what he could do for him, the philosopher disdainfully asked Alexander to stand a little to the side, as he was blocking the sunlight.[55] This reply apparently delighted Alexander, who is reported to have said "But verily, if I were not Alexander, I would like to be Diogenes."[56] At Corinth, Alexander took the title of Hegemon ("leader") and, like Philip, was appointed commander for the coming war against Persia. He also received news of a Thracian uprising.[57]
-
-Balkan campaign
-
-Main article: Alexander's Balkan campaign
-Before crossing to Asia, Alexander wanted to safeguard his northern borders. In the spring of 335 BC, he advanced to suppress several revolts. Starting from Amphipolis, he travelled east into the country of the "Independent Thracians"; and at Mount Haemus, the Macedonian army attacked and defeated the Thracian forces manning the heights.[58] The Macedonians marched into the country of the Triballi, and defeated their army near the Lyginus river[59] (a tributary of the Danube). Alexander then marched for three days to the Danube, encountering the Getae tribe on the opposite shore. Crossing the river at night, he surprised them and forced their army to retreat after the first cavalry skirmish.[60]
-
-News then reached Alexander that the Illyrian chieftain Cleitus and King Glaukias of the Taulantii were in open revolt against his authority. Marching west into Illyria, Alexander defeated each in turn, forcing the two rulers to flee with their troops. With these victories, he secured his northern frontier.[61]
-
-Destruction of Thebes
-
-While Alexander campaigned north, the Thebans and Athenians rebelled once again. Alexander immediately headed south.[62] While the other cities again hesitated, Thebes decided to fight. The Theban resistance was ineffective, and Alexander razed the city and divided its territory between the other Boeotian cities. The end of Thebes cowed Athens, leaving all of Greece temporarily at peace.[62] Alexander then set out on his Asian campaign, leaving Antipater as regent.[63]
-
-Conquest of the Achaemenid Persian Empire
-
-Main articles: Wars of Alexander the Great and Chronology of the expedition of Alexander the Great into Asia
-Asia Minor
-
-Further information: Battle of the Granicus, Siege of Halicarnassus, and Siege of Miletus
-After his victory at the Battle of Chaeronea (338 BC), Philip II began the work of establishing himself as hēgemṓn (Greek: ἡγεμών) of a league which according to Diodorus was to wage a campaign against the Persians for the sundry grievances Greece suffered in 480 and free the Greek cities of the western coast and islands from Achaemenid rule. In 336 he sent Parmenion, Amyntas, Andromenes, Attalus, and an army of 10,000 men into Anatolia to make preparations for an invasion.[64][65] At first, all went well. The Greek cities on the western coast of Anatolia revolted until the news arrived that Philip had been murdered and had been succeeded by his young son Alexander. The Macedonians were demoralized by Philip's death and were subsequently defeated near Magnesia by the Achaemenids under the command of the mercenary Memnon of Rhodes.[64][65]
-
-Taking over the invasion project of Philip II, Alexander's army crossed the Hellespont in 334 BC with approximately 48,100 soldiers, 6,100 cavalry and a fleet of 120 ships with crews numbering 38,000,[62] drawn from Macedon and various Greek city-states, mercenaries, and feudally raised soldiers from Thrace, Paionia, and Illyria.[66][i] He showed his intent to conquer the entirety of the Persian Empire by throwing a spear into Asian soil and saying he accepted Asia as a gift from the gods. This also showed Alexander's eagerness to fight, in contrast to his father's preference for diplomacy.[62]
-
-After an initial victory against Persian forces at the Battle of the Granicus, Alexander accepted the surrender of the Persian provincial capital and treasury of Sardis; he then proceeded along the Ionian coast, granting autonomy and democracy to the cities. Miletus, held by Achaemenid forces, required a delicate siege operation, with Persian naval forces nearby. Further south, at Halicarnassus, in Caria, Alexander successfully waged his first large-scale siege, eventually forcing his opponents, the mercenary captain Memnon of Rhodes and the Persian satrap of Caria, Orontobates, to withdraw by sea.[67] Alexander left the government of Caria to a member of the Hecatomnid dynasty, Ada, who adopted Alexander.[68]
-
-From Halicarnassus, Alexander proceeded into mountainous Lycia and the Pamphylian plain, asserting control over all coastal cities to deny the Persians naval bases. From Pamphylia onwards the coast held no major ports and Alexander moved inland. At Termessos, Alexander humbled but did not storm the Pisidian city.[69] At the ancient Phrygian capital of Gordium, Alexander "undid" the hitherto unsolvable Gordian Knot, a feat said to await the future "king of Asia".[70] According to the story, Alexander proclaimed that it did not matter how the knot was undone and hacked it apart with his sword.[71]
-
-The Levant and Syria
-
-Further information: Battle of Issus and Siege of Tyre (332 BC)
-In spring 333 BC, Alexander crossed the Taurus into Cilicia. After a long pause due to an illness, he marched on towards Syria. Though outmanoeuvered by Darius's significantly larger army, he marched back to Cilicia, where he defeated Darius at Issus. Darius fled the battle, causing his army to collapse, and left behind his wife, his two daughters, his mother Sisygambis, and a fabulous treasure.[72] He offered a peace treaty that included the lands he had already lost, and a ransom of 10,000 talents for his family. Alexander replied that since he was now king of Asia, it was he alone who decided territorial divisions.[73] Alexander proceeded to take possession of Syria, and most of the coast of the Levant.[68] In the following year, 332 BC, he was forced to attack Tyre, which he captured after a long and difficult siege.[74][75] The men of military age were massacred and the women and children sold into slavery.[76]
-
-Egypt
-
-Further information: Siege of Gaza (332 BCE)
-When Alexander destroyed Tyre, most of the towns on the route to Egypt quickly capitulated. However, Alexander was met with resistance at Gaza. The stronghold was heavily fortified and built on a hill, requiring a siege. When "his engineers pointed out to him that because of the height of the mound it would be impossible... this encouraged Alexander all the more to make the attempt".[77] After three unsuccessful assaults, the stronghold fell, but not before Alexander had received a serious shoulder wound. As in Tyre, men of military age were put to the sword and the women and children were sold into slavery.[78]
-"""
diff --git a/tests/old_proxy_tests/tests/llama_index_data/essay.txt b/tests/old_proxy_tests/tests/llama_index_data/essay.txt
deleted file mode 100644
index 7f0350da39f..00000000000
--- a/tests/old_proxy_tests/tests/llama_index_data/essay.txt
+++ /dev/null
@@ -1,353 +0,0 @@
-
-
-What I Worked On
-
-February 2021
-
-Before college the two main things I worked on, outside of school, were writing and programming. I didn't write essays. I wrote what beginning writers were supposed to write then, and probably still are: short stories. My stories were awful. They had hardly any plot, just characters with strong feelings, which I imagined made them deep.
-
-The first programs I tried writing were on the IBM 1401 that our school district used for what was then called "data processing." This was in 9th grade, so I was 13 or 14. The school district's 1401 happened to be in the basement of our junior high school, and my friend Rich Draves and I got permission to use it. It was like a mini Bond villain's lair down there, with all these alien-looking machines — CPU, disk drives, printer, card reader — sitting up on a raised floor under bright fluorescent lights.
-
-The language we used was an early version of Fortran. You had to type programs on punch cards, then stack them in the card reader and press a button to load the program into memory and run it. The result would ordinarily be to print something on the spectacularly loud printer.
-
-I was puzzled by the 1401. I couldn't figure out what to do with it. And in retrospect there's not much I could have done with it. The only form of input to programs was data stored on punched cards, and I didn't have any data stored on punched cards. The only other option was to do things that didn't rely on any input, like calculate approximations of pi, but I didn't know enough math to do anything interesting of that type. So I'm not surprised I can't remember any programs I wrote, because they can't have done much. My clearest memory is of the moment I learned it was possible for programs not to terminate, when one of mine didn't. On a machine without time-sharing, this was a social as well as a technical error, as the data center manager's expression made clear.
-
-With microcomputers, everything changed. Now you could have a computer sitting right in front of you, on a desk, that could respond to your keystrokes as it was running instead of just churning through a stack of punch cards and then stopping. [1]
-
-The first of my friends to get a microcomputer built it himself. It was sold as a kit by Heathkit. I remember vividly how impressed and envious I felt watching him sitting in front of it, typing programs right into the computer.
-
-Computers were expensive in those days and it took me years of nagging before I convinced my father to buy one, a TRS-80, in about 1980. The gold standard then was the Apple II, but a TRS-80 was good enough. This was when I really started programming. I wrote simple games, a program to predict how high my model rockets would fly, and a word processor that my father used to write at least one book. There was only room in memory for about 2 pages of text, so he'd write 2 pages at a time and then print them out, but it was a lot better than a typewriter.
-
-Though I liked programming, I didn't plan to study it in college. In college I was going to study philosophy, which sounded much more powerful. It seemed, to my naive high school self, to be the study of the ultimate truths, compared to which the things studied in other fields would be mere domain knowledge. What I discovered when I got to college was that the other fields took up so much of the space of ideas that there wasn't much left for these supposed ultimate truths. All that seemed left for philosophy were edge cases that people in other fields felt could safely be ignored.
-
-I couldn't have put this into words when I was 18. All I knew at the time was that I kept taking philosophy courses and they kept being boring. So I decided to switch to AI.
-
-AI was in the air in the mid 1980s, but there were two things especially that made me want to work on it: a novel by Heinlein called The Moon is a Harsh Mistress, which featured an intelligent computer called Mike, and a PBS documentary that showed Terry Winograd using SHRDLU. I haven't tried rereading The Moon is a Harsh Mistress, so I don't know how well it has aged, but when I read it I was drawn entirely into its world. It seemed only a matter of time before we'd have Mike, and when I saw Winograd using SHRDLU, it seemed like that time would be a few years at most. All you had to do was teach SHRDLU more words.
-
-There weren't any classes in AI at Cornell then, not even graduate classes, so I started trying to teach myself. Which meant learning Lisp, since in those days Lisp was regarded as the language of AI. The commonly used programming languages then were pretty primitive, and programmers' ideas correspondingly so. The default language at Cornell was a Pascal-like language called PL/I, and the situation was similar elsewhere. Learning Lisp expanded my concept of a program so fast that it was years before I started to have a sense of where the new limits were. This was more like it; this was what I had expected college to do. It wasn't happening in a class, like it was supposed to, but that was ok. For the next couple years I was on a roll. I knew what I was going to do.
-
-For my undergraduate thesis, I reverse-engineered SHRDLU. My God did I love working on that program. It was a pleasing bit of code, but what made it even more exciting was my belief — hard to imagine now, but not unique in 1985 — that it was already climbing the lower slopes of intelligence.
-
-I had gotten into a program at Cornell that didn't make you choose a major. You could take whatever classes you liked, and choose whatever you liked to put on your degree. I of course chose "Artificial Intelligence." When I got the actual physical diploma, I was dismayed to find that the quotes had been included, which made them read as scare-quotes. At the time this bothered me, but now it seems amusingly accurate, for reasons I was about to discover.
-
-I applied to 3 grad schools: MIT and Yale, which were renowned for AI at the time, and Harvard, which I'd visited because Rich Draves went there, and was also home to Bill Woods, who'd invented the type of parser I used in my SHRDLU clone. Only Harvard accepted me, so that was where I went.
-
-I don't remember the moment it happened, or if there even was a specific moment, but during the first year of grad school I realized that AI, as practiced at the time, was a hoax. By which I mean the sort of AI in which a program that's told "the dog is sitting on the chair" translates this into some formal representation and adds it to the list of things it knows.
-
-What these programs really showed was that there's a subset of natural language that's a formal language. But a very proper subset. It was clear that there was an unbridgeable gap between what they could do and actually understanding natural language. It was not, in fact, simply a matter of teaching SHRDLU more words. That whole way of doing AI, with explicit data structures representing concepts, was not going to work. Its brokenness did, as so often happens, generate a lot of opportunities to write papers about various band-aids that could be applied to it, but it was never going to get us Mike.
-
-So I looked around to see what I could salvage from the wreckage of my plans, and there was Lisp. I knew from experience that Lisp was interesting for its own sake and not just for its association with AI, even though that was the main reason people cared about it at the time. So I decided to focus on Lisp. In fact, I decided to write a book about Lisp hacking. It's scary to think how little I knew about Lisp hacking when I started writing that book. But there's nothing like writing a book about something to help you learn it. The book, On Lisp, wasn't published till 1993, but I wrote much of it in grad school.
-
-Computer Science is an uneasy alliance between two halves, theory and systems. The theory people prove things, and the systems people build things. I wanted to build things. I had plenty of respect for theory — indeed, a sneaking suspicion that it was the more admirable of the two halves — but building things seemed so much more exciting.
-
-The problem with systems work, though, was that it didn't last. Any program you wrote today, no matter how good, would be obsolete in a couple decades at best. People might mention your software in footnotes, but no one would actually use it. And indeed, it would seem very feeble work. Only people with a sense of the history of the field would even realize that, in its time, it had been good.
-
-There were some surplus Xerox Dandelions floating around the computer lab at one point. Anyone who wanted one to play around with could have one. I was briefly tempted, but they were so slow by present standards; what was the point? No one else wanted one either, so off they went. That was what happened to systems work.
-
-I wanted not just to build things, but to build things that would last.
-
-In this dissatisfied state I went in 1988 to visit Rich Draves at CMU, where he was in grad school. One day I went to visit the Carnegie Institute, where I'd spent a lot of time as a kid. While looking at a painting there I realized something that might seem obvious, but was a big surprise to me. There, right on the wall, was something you could make that would last. Paintings didn't become obsolete. Some of the best ones were hundreds of years old.
-
-And moreover this was something you could make a living doing. Not as easily as you could by writing software, of course, but I thought if you were really industrious and lived really cheaply, it had to be possible to make enough to survive. And as an artist you could be truly independent. You wouldn't have a boss, or even need to get research funding.
-
-I had always liked looking at paintings. Could I make them? I had no idea. I'd never imagined it was even possible. I knew intellectually that people made art — that it didn't just appear spontaneously — but it was as if the people who made it were a different species. They either lived long ago or were mysterious geniuses doing strange things in profiles in Life magazine. The idea of actually being able to make art, to put that verb before that noun, seemed almost miraculous.
-
-That fall I started taking art classes at Harvard. Grad students could take classes in any department, and my advisor, Tom Cheatham, was very easy going. If he even knew about the strange classes I was taking, he never said anything.
-
-So now I was in a PhD program in computer science, yet planning to be an artist, yet also genuinely in love with Lisp hacking and working away at On Lisp. In other words, like many a grad student, I was working energetically on multiple projects that were not my thesis.
-
-I didn't see a way out of this situation. I didn't want to drop out of grad school, but how else was I going to get out? I remember when my friend Robert Morris got kicked out of Cornell for writing the internet worm of 1988, I was envious that he'd found such a spectacular way to get out of grad school.
-
-Then one day in April 1990 a crack appeared in the wall. I ran into professor Cheatham and he asked if I was far enough along to graduate that June. I didn't have a word of my dissertation written, but in what must have been the quickest bit of thinking in my life, I decided to take a shot at writing one in the 5 weeks or so that remained before the deadline, reusing parts of On Lisp where I could, and I was able to respond, with no perceptible delay "Yes, I think so. I'll give you something to read in a few days."
-
-I picked applications of continuations as the topic. In retrospect I should have written about macros and embedded languages. There's a whole world there that's barely been explored. But all I wanted was to get out of grad school, and my rapidly written dissertation sufficed, just barely.
-
-Meanwhile I was applying to art schools. I applied to two: RISD in the US, and the Accademia di Belli Arti in Florence, which, because it was the oldest art school, I imagined would be good. RISD accepted me, and I never heard back from the Accademia, so off to Providence I went.
-
-I'd applied for the BFA program at RISD, which meant in effect that I had to go to college again. This was not as strange as it sounds, because I was only 25, and art schools are full of people of different ages. RISD counted me as a transfer sophomore and said I had to do the foundation that summer. The foundation means the classes that everyone has to take in fundamental subjects like drawing, color, and design.
-
-Toward the end of the summer I got a big surprise: a letter from the Accademia, which had been delayed because they'd sent it to Cambridge England instead of Cambridge Massachusetts, inviting me to take the entrance exam in Florence that fall. This was now only weeks away. My nice landlady let me leave my stuff in her attic. I had some money saved from consulting work I'd done in grad school; there was probably enough to last a year if I lived cheaply. Now all I had to do was learn Italian.
-
-Only stranieri (foreigners) had to take this entrance exam. In retrospect it may well have been a way of excluding them, because there were so many stranieri attracted by the idea of studying art in Florence that the Italian students would otherwise have been outnumbered. I was in decent shape at painting and drawing from the RISD foundation that summer, but I still don't know how I managed to pass the written exam. I remember that I answered the essay question by writing about Cezanne, and that I cranked up the intellectual level as high as I could to make the most of my limited vocabulary. [2]
-
-I'm only up to age 25 and already there are such conspicuous patterns. Here I was, yet again about to attend some august institution in the hopes of learning about some prestigious subject, and yet again about to be disappointed. The students and faculty in the painting department at the Accademia were the nicest people you could imagine, but they had long since arrived at an arrangement whereby the students wouldn't require the faculty to teach anything, and in return the faculty wouldn't require the students to learn anything. And at the same time all involved would adhere outwardly to the conventions of a 19th century atelier. We actually had one of those little stoves, fed with kindling, that you see in 19th century studio paintings, and a nude model sitting as close to it as possible without getting burned. Except hardly anyone else painted her besides me. The rest of the students spent their time chatting or occasionally trying to imitate things they'd seen in American art magazines.
-
-Our model turned out to live just down the street from me. She made a living from a combination of modelling and making fakes for a local antique dealer. She'd copy an obscure old painting out of a book, and then he'd take the copy and maltreat it to make it look old. [3]
-
-While I was a student at the Accademia I started painting still lives in my bedroom at night. These paintings were tiny, because the room was, and because I painted them on leftover scraps of canvas, which was all I could afford at the time. Painting still lives is different from painting people, because the subject, as its name suggests, can't move. People can't sit for more than about 15 minutes at a time, and when they do they don't sit very still. So the traditional m.o. for painting people is to know how to paint a generic person, which you then modify to match the specific person you're painting. Whereas a still life you can, if you want, copy pixel by pixel from what you're seeing. You don't want to stop there, of course, or you get merely photographic accuracy, and what makes a still life interesting is that it's been through a head. You want to emphasize the visual cues that tell you, for example, that the reason the color changes suddenly at a certain point is that it's the edge of an object. By subtly emphasizing such things you can make paintings that are more realistic than photographs not just in some metaphorical sense, but in the strict information-theoretic sense. [4]
-
-I liked painting still lives because I was curious about what I was seeing. In everyday life, we aren't consciously aware of much we're seeing. Most visual perception is handled by low-level processes that merely tell your brain "that's a water droplet" without telling you details like where the lightest and darkest points are, or "that's a bush" without telling you the shape and position of every leaf. This is a feature of brains, not a bug. In everyday life it would be distracting to notice every leaf on every bush. But when you have to paint something, you have to look more closely, and when you do there's a lot to see. You can still be noticing new things after days of trying to paint something people usually take for granted, just as you can after days of trying to write an essay about something people usually take for granted.
-
-This is not the only way to paint. I'm not 100% sure it's even a good way to paint. But it seemed a good enough bet to be worth trying.
-
-Our teacher, professor Ulivi, was a nice guy. He could see I worked hard, and gave me a good grade, which he wrote down in a sort of passport each student had. But the Accademia wasn't teaching me anything except Italian, and my money was running out, so at the end of the first year I went back to the US.
-
-I wanted to go back to RISD, but I was now broke and RISD was very expensive, so I decided to get a job for a year and then return to RISD the next fall. I got one at a company called Interleaf, which made software for creating documents. You mean like Microsoft Word? Exactly. That was how I learned that low end software tends to eat high end software. But Interleaf still had a few years to live yet. [5]
-
-Interleaf had done something pretty bold. Inspired by Emacs, they'd added a scripting language, and even made the scripting language a dialect of Lisp. Now they wanted a Lisp hacker to write things in it. This was the closest thing I've had to a normal job, and I hereby apologize to my boss and coworkers, because I was a bad employee. Their Lisp was the thinnest icing on a giant C cake, and since I didn't know C and didn't want to learn it, I never understood most of the software. Plus I was terribly irresponsible. This was back when a programming job meant showing up every day during certain working hours. That seemed unnatural to me, and on this point the rest of the world is coming around to my way of thinking, but at the time it caused a lot of friction. Toward the end of the year I spent much of my time surreptitiously working on On Lisp, which I had by this time gotten a contract to publish.
-
-The good part was that I got paid huge amounts of money, especially by art student standards. In Florence, after paying my part of the rent, my budget for everything else had been $7 a day. Now I was getting paid more than 4 times that every hour, even when I was just sitting in a meeting. By living cheaply I not only managed to save enough to go back to RISD, but also paid off my college loans.
-
-I learned some useful things at Interleaf, though they were mostly about what not to do. I learned that it's better for technology companies to be run by product people than sales people (though sales is a real skill and people who are good at it are really good at it), that it leads to bugs when code is edited by too many people, that cheap office space is no bargain if it's depressing, that planned meetings are inferior to corridor conversations, that big, bureaucratic customers are a dangerous source of money, and that there's not much overlap between conventional office hours and the optimal time for hacking, or conventional offices and the optimal place for it.
-
-But the most important thing I learned, and which I used in both Viaweb and Y Combinator, is that the low end eats the high end: that it's good to be the "entry level" option, even though that will be less prestigious, because if you're not, someone else will be, and will squash you against the ceiling. Which in turn means that prestige is a danger sign.
-
-When I left to go back to RISD the next fall, I arranged to do freelance work for the group that did projects for customers, and this was how I survived for the next several years. When I came back to visit for a project later on, someone told me about a new thing called HTML, which was, as he described it, a derivative of SGML. Markup language enthusiasts were an occupational hazard at Interleaf and I ignored him, but this HTML thing later became a big part of my life.
-
-In the fall of 1992 I moved back to Providence to continue at RISD. The foundation had merely been intro stuff, and the Accademia had been a (very civilized) joke. Now I was going to see what real art school was like. But alas it was more like the Accademia than not. Better organized, certainly, and a lot more expensive, but it was now becoming clear that art school did not bear the same relationship to art that medical school bore to medicine. At least not the painting department. The textile department, which my next door neighbor belonged to, seemed to be pretty rigorous. No doubt illustration and architecture were too. But painting was post-rigorous. Painting students were supposed to express themselves, which to the more worldly ones meant to try to cook up some sort of distinctive signature style.
-
-A signature style is the visual equivalent of what in show business is known as a "schtick": something that immediately identifies the work as yours and no one else's. For example, when you see a painting that looks like a certain kind of cartoon, you know it's by Roy Lichtenstein. So if you see a big painting of this type hanging in the apartment of a hedge fund manager, you know he paid millions of dollars for it. That's not always why artists have a signature style, but it's usually why buyers pay a lot for such work. [6]
-
-There were plenty of earnest students too: kids who "could draw" in high school, and now had come to what was supposed to be the best art school in the country, to learn to draw even better. They tended to be confused and demoralized by what they found at RISD, but they kept going, because painting was what they did. I was not one of the kids who could draw in high school, but at RISD I was definitely closer to their tribe than the tribe of signature style seekers.
-
-I learned a lot in the color class I took at RISD, but otherwise I was basically teaching myself to paint, and I could do that for free. So in 1993 I dropped out. I hung around Providence for a bit, and then my college friend Nancy Parmet did me a big favor. A rent-controlled apartment in a building her mother owned in New York was becoming vacant. Did I want it? It wasn't much more than my current place, and New York was supposed to be where the artists were. So yes, I wanted it! [7]
-
-Asterix comics begin by zooming in on a tiny corner of Roman Gaul that turns out not to be controlled by the Romans. You can do something similar on a map of New York City: if you zoom in on the Upper East Side, there's a tiny corner that's not rich, or at least wasn't in 1993. It's called Yorkville, and that was my new home. Now I was a New York artist — in the strictly technical sense of making paintings and living in New York.
-
-I was nervous about money, because I could sense that Interleaf was on the way down. Freelance Lisp hacking work was very rare, and I didn't want to have to program in another language, which in those days would have meant C++ if I was lucky. So with my unerring nose for financial opportunity, I decided to write another book on Lisp. This would be a popular book, the sort of book that could be used as a textbook. I imagined myself living frugally off the royalties and spending all my time painting. (The painting on the cover of this book, ANSI Common Lisp, is one that I painted around this time.)
-
-The best thing about New York for me was the presence of Idelle and Julian Weber. Idelle Weber was a painter, one of the early photorealists, and I'd taken her painting class at Harvard. I've never known a teacher more beloved by her students. Large numbers of former students kept in touch with her, including me. After I moved to New York I became her de facto studio assistant.
-
-She liked to paint on big, square canvases, 4 to 5 feet on a side. One day in late 1994 as I was stretching one of these monsters there was something on the radio about a famous fund manager. He wasn't that much older than me, and was super rich. The thought suddenly occurred to me: why don't I become rich? Then I'll be able to work on whatever I want.
-
-Meanwhile I'd been hearing more and more about this new thing called the World Wide Web. Robert Morris showed it to me when I visited him in Cambridge, where he was now in grad school at Harvard. It seemed to me that the web would be a big deal. I'd seen what graphical user interfaces had done for the popularity of microcomputers. It seemed like the web would do the same for the internet.
-
-If I wanted to get rich, here was the next train leaving the station. I was right about that part. What I got wrong was the idea. I decided we should start a company to put art galleries online. I can't honestly say, after reading so many Y Combinator applications, that this was the worst startup idea ever, but it was up there. Art galleries didn't want to be online, and still don't, not the fancy ones. That's not how they sell. I wrote some software to generate web sites for galleries, and Robert wrote some to resize images and set up an http server to serve the pages. Then we tried to sign up galleries. To call this a difficult sale would be an understatement. It was difficult to give away. A few galleries let us make sites for them for free, but none paid us.
-
-Then some online stores started to appear, and I realized that except for the order buttons they were identical to the sites we'd been generating for galleries. This impressive-sounding thing called an "internet storefront" was something we already knew how to build.
-
-So in the summer of 1995, after I submitted the camera-ready copy of ANSI Common Lisp to the publishers, we started trying to write software to build online stores. At first this was going to be normal desktop software, which in those days meant Windows software. That was an alarming prospect, because neither of us knew how to write Windows software or wanted to learn. We lived in the Unix world. But we decided we'd at least try writing a prototype store builder on Unix. Robert wrote a shopping cart, and I wrote a new site generator for stores — in Lisp, of course.
-
-We were working out of Robert's apartment in Cambridge. His roommate was away for big chunks of time, during which I got to sleep in his room. For some reason there was no bed frame or sheets, just a mattress on the floor. One morning as I was lying on this mattress I had an idea that made me sit up like a capital L. What if we ran the software on the server, and let users control it by clicking on links? Then we'd never have to write anything to run on users' computers. We could generate the sites on the same server we'd serve them from. Users wouldn't need anything more than a browser.
-
-This kind of software, known as a web app, is common now, but at the time it wasn't clear that it was even possible. To find out, we decided to try making a version of our store builder that you could control through the browser. A couple days later, on August 12, we had one that worked. The UI was horrible, but it proved you could build a whole store through the browser, without any client software or typing anything into the command line on the server.
-
-Now we felt like we were really onto something. I had visions of a whole new generation of software working this way. You wouldn't need versions, or ports, or any of that crap. At Interleaf there had been a whole group called Release Engineering that seemed to be at least as big as the group that actually wrote the software. Now you could just update the software right on the server.
-
-We started a new company we called Viaweb, after the fact that our software worked via the web, and we got $10,000 in seed funding from Idelle's husband Julian. In return for that and doing the initial legal work and giving us business advice, we gave him 10% of the company. Ten years later this deal became the model for Y Combinator's. We knew founders needed something like this, because we'd needed it ourselves.
-
-At this stage I had a negative net worth, because the thousand dollars or so I had in the bank was more than counterbalanced by what I owed the government in taxes. (Had I diligently set aside the proper proportion of the money I'd made consulting for Interleaf? No, I had not.) So although Robert had his graduate student stipend, I needed that seed funding to live on.
-
-We originally hoped to launch in September, but we got more ambitious about the software as we worked on it. Eventually we managed to build a WYSIWYG site builder, in the sense that as you were creating pages, they looked exactly like the static ones that would be generated later, except that instead of leading to static pages, the links all referred to closures stored in a hash table on the server.
-
-It helped to have studied art, because the main goal of an online store builder is to make users look legit, and the key to looking legit is high production values. If you get page layouts and fonts and colors right, you can make a guy running a store out of his bedroom look more legit than a big company.
-
-(If you're curious why my site looks so old-fashioned, it's because it's still made with this software. It may look clunky today, but in 1996 it was the last word in slick.)
-
-In September, Robert rebelled. "We've been working on this for a month," he said, "and it's still not done." This is funny in retrospect, because he would still be working on it almost 3 years later. But I decided it might be prudent to recruit more programmers, and I asked Robert who else in grad school with him was really good. He recommended Trevor Blackwell, which surprised me at first, because at that point I knew Trevor mainly for his plan to reduce everything in his life to a stack of notecards, which he carried around with him. But Rtm was right, as usual. Trevor turned out to be a frighteningly effective hacker.
-
-It was a lot of fun working with Robert and Trevor. They're the two most independent-minded people I know, and in completely different ways. If you could see inside Rtm's brain it would look like a colonial New England church, and if you could see inside Trevor's it would look like the worst excesses of Austrian Rococo.
-
-We opened for business, with 6 stores, in January 1996. It was just as well we waited a few months, because although we worried we were late, we were actually almost fatally early. There was a lot of talk in the press then about ecommerce, but not many people actually wanted online stores. [8]
-
-There were three main parts to the software: the editor, which people used to build sites and which I wrote, the shopping cart, which Robert wrote, and the manager, which kept track of orders and statistics, and which Trevor wrote. In its time, the editor was one of the best general-purpose site builders. I kept the code tight and didn't have to integrate with any other software except Robert's and Trevor's, so it was quite fun to work on. If all I'd had to do was work on this software, the next 3 years would have been the easiest of my life. Unfortunately I had to do a lot more, all of it stuff I was worse at than programming, and the next 3 years were instead the most stressful.
-
-There were a lot of startups making ecommerce software in the second half of the 90s. We were determined to be the Microsoft Word, not the Interleaf. Which meant being easy to use and inexpensive. It was lucky for us that we were poor, because that caused us to make Viaweb even more inexpensive than we realized. We charged $100 a month for a small store and $300 a month for a big one. This low price was a big attraction, and a constant thorn in the sides of competitors, but it wasn't because of some clever insight that we set the price low. We had no idea what businesses paid for things. $300 a month seemed like a lot of money to us.
-
-We did a lot of things right by accident like that. For example, we did what's now called "doing things that don't scale," although at the time we would have described it as "being so lame that we're driven to the most desperate measures to get users." The most common of which was building stores for them. This seemed particularly humiliating, since the whole raison d'etre of our software was that people could use it to make their own stores. But anything to get users.
-
-We learned a lot more about retail than we wanted to know. For example, that if you could only have a small image of a man's shirt (and all images were small then by present standards), it was better to have a closeup of the collar than a picture of the whole shirt. The reason I remember learning this was that it meant I had to rescan about 30 images of men's shirts. My first set of scans were so beautiful too.
-
-Though this felt wrong, it was exactly the right thing to be doing. Building stores for users taught us about retail, and about how it felt to use our software. I was initially both mystified and repelled by "business" and thought we needed a "business person" to be in charge of it, but once we started to get users, I was converted, in much the same way I was converted to fatherhood once I had kids. Whatever users wanted, I was all theirs. Maybe one day we'd have so many users that I couldn't scan their images for them, but in the meantime there was nothing more important to do.
-
-Another thing I didn't get at the time is that growth rate is the ultimate test of a startup. Our growth rate was fine. We had about 70 stores at the end of 1996 and about 500 at the end of 1997. I mistakenly thought the thing that mattered was the absolute number of users. And that is the thing that matters in the sense that that's how much money you're making, and if you're not making enough, you might go out of business. But in the long term the growth rate takes care of the absolute number. If we'd been a startup I was advising at Y Combinator, I would have said: Stop being so stressed out, because you're doing fine. You're growing 7x a year. Just don't hire too many more people and you'll soon be profitable, and then you'll control your own destiny.
-
-Alas I hired lots more people, partly because our investors wanted me to, and partly because that's what startups did during the Internet Bubble. A company with just a handful of employees would have seemed amateurish. So we didn't reach breakeven until about when Yahoo bought us in the summer of 1998. Which in turn meant we were at the mercy of investors for the entire life of the company. And since both we and our investors were noobs at startups, the result was a mess even by startup standards.
-
-It was a huge relief when Yahoo bought us. In principle our Viaweb stock was valuable. It was a share in a business that was profitable and growing rapidly. But it didn't feel very valuable to me; I had no idea how to value a business, but I was all too keenly aware of the near-death experiences we seemed to have every few months. Nor had I changed my grad student lifestyle significantly since we started. So when Yahoo bought us it felt like going from rags to riches. Since we were going to California, I bought a car, a yellow 1998 VW GTI. I remember thinking that its leather seats alone were by far the most luxurious thing I owned.
-
-The next year, from the summer of 1998 to the summer of 1999, must have been the least productive of my life. I didn't realize it at the time, but I was worn out from the effort and stress of running Viaweb. For a while after I got to California I tried to continue my usual m.o. of programming till 3 in the morning, but fatigue combined with Yahoo's prematurely aged culture and grim cube farm in Santa Clara gradually dragged me down. After a few months it felt disconcertingly like working at Interleaf.
-
-Yahoo had given us a lot of options when they bought us. At the time I thought Yahoo was so overvalued that they'd never be worth anything, but to my astonishment the stock went up 5x in the next year. I hung on till the first chunk of options vested, then in the summer of 1999 I left. It had been so long since I'd painted anything that I'd half forgotten why I was doing this. My brain had been entirely full of software and men's shirts for 4 years. But I had done this to get rich so I could paint, I reminded myself, and now I was rich, so I should go paint.
-
-When I said I was leaving, my boss at Yahoo had a long conversation with me about my plans. I told him all about the kinds of pictures I wanted to paint. At the time I was touched that he took such an interest in me. Now I realize it was because he thought I was lying. My options at that point were worth about $2 million a month. If I was leaving that kind of money on the table, it could only be to go and start some new startup, and if I did, I might take people with me. This was the height of the Internet Bubble, and Yahoo was ground zero of it. My boss was at that moment a billionaire. Leaving then to start a new startup must have seemed to him an insanely, and yet also plausibly, ambitious plan.
-
-But I really was quitting to paint, and I started immediately. There was no time to lose. I'd already burned 4 years getting rich. Now when I talk to founders who are leaving after selling their companies, my advice is always the same: take a vacation. That's what I should have done, just gone off somewhere and done nothing for a month or two, but the idea never occurred to me.
-
-So I tried to paint, but I just didn't seem to have any energy or ambition. Part of the problem was that I didn't know many people in California. I'd compounded this problem by buying a house up in the Santa Cruz Mountains, with a beautiful view but miles from anywhere. I stuck it out for a few more months, then in desperation I went back to New York, where unless you understand about rent control you'll be surprised to hear I still had my apartment, sealed up like a tomb of my old life. Idelle was in New York at least, and there were other people trying to paint there, even though I didn't know any of them.
-
-When I got back to New York I resumed my old life, except now I was rich. It was as weird as it sounds. I resumed all my old patterns, except now there were doors where there hadn't been. Now when I was tired of walking, all I had to do was raise my hand, and (unless it was raining) a taxi would stop to pick me up. Now when I walked past charming little restaurants I could go in and order lunch. It was exciting for a while. Painting started to go better. I experimented with a new kind of still life where I'd paint one painting in the old way, then photograph it and print it, blown up, on canvas, and then use that as the underpainting for a second still life, painted from the same objects (which hopefully hadn't rotted yet).
-
-Meanwhile I looked for an apartment to buy. Now I could actually choose what neighborhood to live in. Where, I asked myself and various real estate agents, is the Cambridge of New York? Aided by occasional visits to actual Cambridge, I gradually realized there wasn't one. Huh.
-
-Around this time, in the spring of 2000, I had an idea. It was clear from our experience with Viaweb that web apps were the future. Why not build a web app for making web apps? Why not let people edit code on our server through the browser, and then host the resulting applications for them? [9] You could run all sorts of services on the servers that these applications could use just by making an API call: making and receiving phone calls, manipulating images, taking credit card payments, etc.
-
-I got so excited about this idea that I couldn't think about anything else. It seemed obvious that this was the future. I didn't particularly want to start another company, but it was clear that this idea would have to be embodied as one, so I decided to move to Cambridge and start it. I hoped to lure Robert into working on it with me, but there I ran into a hitch. Robert was now a postdoc at MIT, and though he'd made a lot of money the last time I'd lured him into working on one of my schemes, it had also been a huge time sink. So while he agreed that it sounded like a plausible idea, he firmly refused to work on it.
-
-Hmph. Well, I'd do it myself then. I recruited Dan Giffin, who had worked for Viaweb, and two undergrads who wanted summer jobs, and we got to work trying to build what it's now clear is about twenty companies and several open source projects worth of software. The language for defining applications would of course be a dialect of Lisp. But I wasn't so naive as to assume I could spring an overt Lisp on a general audience; we'd hide the parentheses, like Dylan did.
-
-By then there was a name for the kind of company Viaweb was, an "application service provider," or ASP. This name didn't last long before it was replaced by "software as a service," but it was current for long enough that I named this new company after it: it was going to be called Aspra.
-
-I started working on the application builder, Dan worked on network infrastructure, and the two undergrads worked on the first two services (images and phone calls). But about halfway through the summer I realized I really didn't want to run a company — especially not a big one, which it was looking like this would have to be. I'd only started Viaweb because I needed the money. Now that I didn't need money anymore, why was I doing this? If this vision had to be realized as a company, then screw the vision. I'd build a subset that could be done as an open source project.
-
-Much to my surprise, the time I spent working on this stuff was not wasted after all. After we started Y Combinator, I would often encounter startups working on parts of this new architecture, and it was very useful to have spent so much time thinking about it and even trying to write some of it.
-
-The subset I would build as an open source project was the new Lisp, whose parentheses I now wouldn't even have to hide. A lot of Lisp hackers dream of building a new Lisp, partly because one of the distinctive features of the language is that it has dialects, and partly, I think, because we have in our minds a Platonic form of Lisp that all existing dialects fall short of. I certainly did. So at the end of the summer Dan and I switched to working on this new dialect of Lisp, which I called Arc, in a house I bought in Cambridge.
-
-The following spring, lightning struck. I was invited to give a talk at a Lisp conference, so I gave one about how we'd used Lisp at Viaweb. Afterward I put a postscript file of this talk online, on paulgraham.com, which I'd created years before using Viaweb but had never used for anything. In one day it got 30,000 page views. What on earth had happened? The referring urls showed that someone had posted it on Slashdot. [10]
-
-Wow, I thought, there's an audience. If I write something and put it on the web, anyone can read it. That may seem obvious now, but it was surprising then. In the print era there was a narrow channel to readers, guarded by fierce monsters known as editors. The only way to get an audience for anything you wrote was to get it published as a book, or in a newspaper or magazine. Now anyone could publish anything.
-
-This had been possible in principle since 1993, but not many people had realized it yet. I had been intimately involved with building the infrastructure of the web for most of that time, and a writer as well, and it had taken me 8 years to realize it. Even then it took me several years to understand the implications. It meant there would be a whole new generation of essays. [11]
-
-In the print era, the channel for publishing essays had been vanishingly small. Except for a few officially anointed thinkers who went to the right parties in New York, the only people allowed to publish essays were specialists writing about their specialties. There were so many essays that had never been written, because there had been no way to publish them. Now they could be, and I was going to write them. [12]
-
-I've worked on several different things, but to the extent there was a turning point where I figured out what to work on, it was when I started publishing essays online. From then on I knew that whatever else I did, I'd always write essays too.
-
-I knew that online essays would be a marginal medium at first. Socially they'd seem more like rants posted by nutjobs on their GeoCities sites than the genteel and beautifully typeset compositions published in The New Yorker. But by this point I knew enough to find that encouraging instead of discouraging.
-
-One of the most conspicuous patterns I've noticed in my life is how well it has worked, for me at least, to work on things that weren't prestigious. Still life has always been the least prestigious form of painting. Viaweb and Y Combinator both seemed lame when we started them. I still get the glassy eye from strangers when they ask what I'm writing, and I explain that it's an essay I'm going to publish on my web site. Even Lisp, though prestigious intellectually in something like the way Latin is, also seems about as hip.
-
-It's not that unprestigious types of work are good per se. But when you find yourself drawn to some kind of work despite its current lack of prestige, it's a sign both that there's something real to be discovered there, and that you have the right kind of motives. Impure motives are a big danger for the ambitious. If anything is going to lead you astray, it will be the desire to impress people. So while working on things that aren't prestigious doesn't guarantee you're on the right track, it at least guarantees you're not on the most common type of wrong one.
-
-Over the next several years I wrote lots of essays about all kinds of different topics. O'Reilly reprinted a collection of them as a book, called Hackers & Painters after one of the essays in it. I also worked on spam filters, and did some more painting. I used to have dinners for a group of friends every thursday night, which taught me how to cook for groups. And I bought another building in Cambridge, a former candy factory (and later, twas said, porn studio), to use as an office.
-
-One night in October 2003 there was a big party at my house. It was a clever idea of my friend Maria Daniels, who was one of the thursday diners. Three separate hosts would all invite their friends to one party. So for every guest, two thirds of the other guests would be people they didn't know but would probably like. One of the guests was someone I didn't know but would turn out to like a lot: a woman called Jessica Livingston. A couple days later I asked her out.
-
-Jessica was in charge of marketing at a Boston investment bank. This bank thought it understood startups, but over the next year, as she met friends of mine from the startup world, she was surprised how different reality was. And how colorful their stories were. So she decided to compile a book of interviews with startup founders.
-
-When the bank had financial problems and she had to fire half her staff, she started looking for a new job. In early 2005 she interviewed for a marketing job at a Boston VC firm. It took them weeks to make up their minds, and during this time I started telling her about all the things that needed to be fixed about venture capital. They should make a larger number of smaller investments instead of a handful of giant ones, they should be funding younger, more technical founders instead of MBAs, they should let the founders remain as CEO, and so on.
-
-One of my tricks for writing essays had always been to give talks. The prospect of having to stand up in front of a group of people and tell them something that won't waste their time is a great spur to the imagination. When the Harvard Computer Society, the undergrad computer club, asked me to give a talk, I decided I would tell them how to start a startup. Maybe they'd be able to avoid the worst of the mistakes we'd made.
-
-So I gave this talk, in the course of which I told them that the best sources of seed funding were successful startup founders, because then they'd be sources of advice too. Whereupon it seemed they were all looking expectantly at me. Horrified at the prospect of having my inbox flooded by business plans (if I'd only known), I blurted out "But not me!" and went on with the talk. But afterward it occurred to me that I should really stop procrastinating about angel investing. I'd been meaning to since Yahoo bought us, and now it was 7 years later and I still hadn't done one angel investment.
-
-Meanwhile I had been scheming with Robert and Trevor about projects we could work on together. I missed working with them, and it seemed like there had to be something we could collaborate on.
-
-As Jessica and I were walking home from dinner on March 11, at the corner of Garden and Walker streets, these three threads converged. Screw the VCs who were taking so long to make up their minds. We'd start our own investment firm and actually implement the ideas we'd been talking about. I'd fund it, and Jessica could quit her job and work for it, and we'd get Robert and Trevor as partners too. [13]
-
-Once again, ignorance worked in our favor. We had no idea how to be angel investors, and in Boston in 2005 there were no Ron Conways to learn from. So we just made what seemed like the obvious choices, and some of the things we did turned out to be novel.
-
-There are multiple components to Y Combinator, and we didn't figure them all out at once. The part we got first was to be an angel firm. In those days, those two words didn't go together. There were VC firms, which were organized companies with people whose job it was to make investments, but they only did big, million dollar investments. And there were angels, who did smaller investments, but these were individuals who were usually focused on other things and made investments on the side. And neither of them helped founders enough in the beginning. We knew how helpless founders were in some respects, because we remembered how helpless we'd been. For example, one thing Julian had done for us that seemed to us like magic was to get us set up as a company. We were fine writing fairly difficult software, but actually getting incorporated, with bylaws and stock and all that stuff, how on earth did you do that? Our plan was not only to make seed investments, but to do for startups everything Julian had done for us.
-
-YC was not organized as a fund. It was cheap enough to run that we funded it with our own money. That went right by 99% of readers, but professional investors are thinking "Wow, that means they got all the returns." But once again, this was not due to any particular insight on our part. We didn't know how VC firms were organized. It never occurred to us to try to raise a fund, and if it had, we wouldn't have known where to start. [14]
-
-The most distinctive thing about YC is the batch model: to fund a bunch of startups all at once, twice a year, and then to spend three months focusing intensively on trying to help them. That part we discovered by accident, not merely implicitly but explicitly due to our ignorance about investing. We needed to get experience as investors. What better way, we thought, than to fund a whole bunch of startups at once? We knew undergrads got temporary jobs at tech companies during the summer. Why not organize a summer program where they'd start startups instead? We wouldn't feel guilty for being in a sense fake investors, because they would in a similar sense be fake founders. So while we probably wouldn't make much money out of it, we'd at least get to practice being investors on them, and they for their part would probably have a more interesting summer than they would working at Microsoft.
-
-We'd use the building I owned in Cambridge as our headquarters. We'd all have dinner there once a week — on tuesdays, since I was already cooking for the thursday diners on thursdays — and after dinner we'd bring in experts on startups to give talks.
-
-We knew undergrads were deciding then about summer jobs, so in a matter of days we cooked up something we called the Summer Founders Program, and I posted an announcement on my site, inviting undergrads to apply. I had never imagined that writing essays would be a way to get "deal flow," as investors call it, but it turned out to be the perfect source. [15] We got 225 applications for the Summer Founders Program, and we were surprised to find that a lot of them were from people who'd already graduated, or were about to that spring. Already this SFP thing was starting to feel more serious than we'd intended.
-
-We invited about 20 of the 225 groups to interview in person, and from those we picked 8 to fund. They were an impressive group. That first batch included reddit, Justin Kan and Emmett Shear, who went on to found Twitch, Aaron Swartz, who had already helped write the RSS spec and would a few years later become a martyr for open access, and Sam Altman, who would later become the second president of YC. I don't think it was entirely luck that the first batch was so good. You had to be pretty bold to sign up for a weird thing like the Summer Founders Program instead of a summer job at a legit place like Microsoft or Goldman Sachs.
-
-The deal for startups was based on a combination of the deal we did with Julian ($10k for 10%) and what Robert said MIT grad students got for the summer ($6k). We invested $6k per founder, which in the typical two-founder case was $12k, in return for 6%. That had to be fair, because it was twice as good as the deal we ourselves had taken. Plus that first summer, which was really hot, Jessica brought the founders free air conditioners. [16]
-
-Fairly quickly I realized that we had stumbled upon the way to scale startup funding. Funding startups in batches was more convenient for us, because it meant we could do things for a lot of startups at once, but being part of a batch was better for the startups too. It solved one of the biggest problems faced by founders: the isolation. Now you not only had colleagues, but colleagues who understood the problems you were facing and could tell you how they were solving them.
-
-As YC grew, we started to notice other advantages of scale. The alumni became a tight community, dedicated to helping one another, and especially the current batch, whose shoes they remembered being in. We also noticed that the startups were becoming one another's customers. We used to refer jokingly to the "YC GDP," but as YC grows this becomes less and less of a joke. Now lots of startups get their initial set of customers almost entirely from among their batchmates.
-
-I had not originally intended YC to be a full-time job. I was going to do three things: hack, write essays, and work on YC. As YC grew, and I grew more excited about it, it started to take up a lot more than a third of my attention. But for the first few years I was still able to work on other things.
-
-In the summer of 2006, Robert and I started working on a new version of Arc. This one was reasonably fast, because it was compiled into Scheme. To test this new Arc, I wrote Hacker News in it. It was originally meant to be a news aggregator for startup founders and was called Startup News, but after a few months I got tired of reading about nothing but startups. Plus it wasn't startup founders we wanted to reach. It was future startup founders. So I changed the name to Hacker News and the topic to whatever engaged one's intellectual curiosity.
-
-HN was no doubt good for YC, but it was also by far the biggest source of stress for me. If all I'd had to do was select and help founders, life would have been so easy. And that implies that HN was a mistake. Surely the biggest source of stress in one's work should at least be something close to the core of the work. Whereas I was like someone who was in pain while running a marathon not from the exertion of running, but because I had a blister from an ill-fitting shoe. When I was dealing with some urgent problem during YC, there was about a 60% chance it had to do with HN, and a 40% chance it had do with everything else combined. [17]
-
-As well as HN, I wrote all of YC's internal software in Arc. But while I continued to work a good deal in Arc, I gradually stopped working on Arc, partly because I didn't have time to, and partly because it was a lot less attractive to mess around with the language now that we had all this infrastructure depending on it. So now my three projects were reduced to two: writing essays and working on YC.
-
-YC was different from other kinds of work I've done. Instead of deciding for myself what to work on, the problems came to me. Every 6 months there was a new batch of startups, and their problems, whatever they were, became our problems. It was very engaging work, because their problems were quite varied, and the good founders were very effective. If you were trying to learn the most you could about startups in the shortest possible time, you couldn't have picked a better way to do it.
-
-There were parts of the job I didn't like. Disputes between cofounders, figuring out when people were lying to us, fighting with people who maltreated the startups, and so on. But I worked hard even at the parts I didn't like. I was haunted by something Kevin Hale once said about companies: "No one works harder than the boss." He meant it both descriptively and prescriptively, and it was the second part that scared me. I wanted YC to be good, so if how hard I worked set the upper bound on how hard everyone else worked, I'd better work very hard.
-
-One day in 2010, when he was visiting California for interviews, Robert Morris did something astonishing: he offered me unsolicited advice. I can only remember him doing that once before. One day at Viaweb, when I was bent over double from a kidney stone, he suggested that it would be a good idea for him to take me to the hospital. That was what it took for Rtm to offer unsolicited advice. So I remember his exact words very clearly. "You know," he said, "you should make sure Y Combinator isn't the last cool thing you do."
-
-At the time I didn't understand what he meant, but gradually it dawned on me that he was saying I should quit. This seemed strange advice, because YC was doing great. But if there was one thing rarer than Rtm offering advice, it was Rtm being wrong. So this set me thinking. It was true that on my current trajectory, YC would be the last thing I did, because it was only taking up more of my attention. It had already eaten Arc, and was in the process of eating essays too. Either YC was my life's work or I'd have to leave eventually. And it wasn't, so I would.
-
-In the summer of 2012 my mother had a stroke, and the cause turned out to be a blood clot caused by colon cancer. The stroke destroyed her balance, and she was put in a nursing home, but she really wanted to get out of it and back to her house, and my sister and I were determined to help her do it. I used to fly up to Oregon to visit her regularly, and I had a lot of time to think on those flights. On one of them I realized I was ready to hand YC over to someone else.
-
-I asked Jessica if she wanted to be president, but she didn't, so we decided we'd try to recruit Sam Altman. We talked to Robert and Trevor and we agreed to make it a complete changing of the guard. Up till that point YC had been controlled by the original LLC we four had started. But we wanted YC to last for a long time, and to do that it couldn't be controlled by the founders. So if Sam said yes, we'd let him reorganize YC. Robert and I would retire, and Jessica and Trevor would become ordinary partners.
-
-When we asked Sam if he wanted to be president of YC, initially he said no. He wanted to start a startup to make nuclear reactors. But I kept at it, and in October 2013 he finally agreed. We decided he'd take over starting with the winter 2014 batch. For the rest of 2013 I left running YC more and more to Sam, partly so he could learn the job, and partly because I was focused on my mother, whose cancer had returned.
-
-She died on January 15, 2014. We knew this was coming, but it was still hard when it did.
-
-I kept working on YC till March, to help get that batch of startups through Demo Day, then I checked out pretty completely. (I still talk to alumni and to new startups working on things I'm interested in, but that only takes a few hours a week.)
-
-What should I do next? Rtm's advice hadn't included anything about that. I wanted to do something completely different, so I decided I'd paint. I wanted to see how good I could get if I really focused on it. So the day after I stopped working on YC, I started painting. I was rusty and it took a while to get back into shape, but it was at least completely engaging. [18]
-
-I spent most of the rest of 2014 painting. I'd never been able to work so uninterruptedly before, and I got to be better than I had been. Not good enough, but better. Then in November, right in the middle of a painting, I ran out of steam. Up till that point I'd always been curious to see how the painting I was working on would turn out, but suddenly finishing this one seemed like a chore. So I stopped working on it and cleaned my brushes and haven't painted since. So far anyway.
-
-I realize that sounds rather wimpy. But attention is a zero sum game. If you can choose what to work on, and you choose a project that's not the best one (or at least a good one) for you, then it's getting in the way of another project that is. And at 50 there was some opportunity cost to screwing around.
-
-I started writing essays again, and wrote a bunch of new ones over the next few months. I even wrote a couple that weren't about startups. Then in March 2015 I started working on Lisp again.
-
-The distinctive thing about Lisp is that its core is a language defined by writing an interpreter in itself. It wasn't originally intended as a programming language in the ordinary sense. It was meant to be a formal model of computation, an alternative to the Turing machine. If you want to write an interpreter for a language in itself, what's the minimum set of predefined operators you need? The Lisp that John McCarthy invented, or more accurately discovered, is an answer to that question. [19]
-
-McCarthy didn't realize this Lisp could even be used to program computers till his grad student Steve Russell suggested it. Russell translated McCarthy's interpreter into IBM 704 machine language, and from that point Lisp started also to be a programming language in the ordinary sense. But its origins as a model of computation gave it a power and elegance that other languages couldn't match. It was this that attracted me in college, though I didn't understand why at the time.
-
-McCarthy's 1960 Lisp did nothing more than interpret Lisp expressions. It was missing a lot of things you'd want in a programming language. So these had to be added, and when they were, they weren't defined using McCarthy's original axiomatic approach. That wouldn't have been feasible at the time. McCarthy tested his interpreter by hand-simulating the execution of programs. But it was already getting close to the limit of interpreters you could test that way — indeed, there was a bug in it that McCarthy had overlooked. To test a more complicated interpreter, you'd have had to run it, and computers then weren't powerful enough.
-
-Now they are, though. Now you could continue using McCarthy's axiomatic approach till you'd defined a complete programming language. And as long as every change you made to McCarthy's Lisp was a discoveredness-preserving transformation, you could, in principle, end up with a complete language that had this quality. Harder to do than to talk about, of course, but if it was possible in principle, why not try? So I decided to take a shot at it. It took 4 years, from March 26, 2015 to October 12, 2019. It was fortunate that I had a precisely defined goal, or it would have been hard to keep at it for so long.
-
-I wrote this new Lisp, called Bel, in itself in Arc. That may sound like a contradiction, but it's an indication of the sort of trickery I had to engage in to make this work. By means of an egregious collection of hacks I managed to make something close enough to an interpreter written in itself that could actually run. Not fast, but fast enough to test.
-
-I had to ban myself from writing essays during most of this time, or I'd never have finished. In late 2015 I spent 3 months writing essays, and when I went back to working on Bel I could barely understand the code. Not so much because it was badly written as because the problem is so convoluted. When you're working on an interpreter written in itself, it's hard to keep track of what's happening at what level, and errors can be practically encrypted by the time you get them.
-
-So I said no more essays till Bel was done. But I told few people about Bel while I was working on it. So for years it must have seemed that I was doing nothing, when in fact I was working harder than I'd ever worked on anything. Occasionally after wrestling for hours with some gruesome bug I'd check Twitter or HN and see someone asking "Does Paul Graham still code?"
-
-Working on Bel was hard but satisfying. I worked on it so intensively that at any given time I had a decent chunk of the code in my head and could write more there. I remember taking the boys to the coast on a sunny day in 2015 and figuring out how to deal with some problem involving continuations while I watched them play in the tide pools. It felt like I was doing life right. I remember that because I was slightly dismayed at how novel it felt. The good news is that I had more moments like this over the next few years.
-
-In the summer of 2016 we moved to England. We wanted our kids to see what it was like living in another country, and since I was a British citizen by birth, that seemed the obvious choice. We only meant to stay for a year, but we liked it so much that we still live there. So most of Bel was written in England.
-
-In the fall of 2019, Bel was finally finished. Like McCarthy's original Lisp, it's a spec rather than an implementation, although like McCarthy's Lisp it's a spec expressed as code.
-
-Now that I could write essays again, I wrote a bunch about topics I'd had stacked up. I kept writing essays through 2020, but I also started to think about other things I could work on. How should I choose what to do? Well, how had I chosen what to work on in the past? I wrote an essay for myself to answer that question, and I was surprised how long and messy the answer turned out to be. If this surprised me, who'd lived it, then I thought perhaps it would be interesting to other people, and encouraging to those with similarly messy lives. So I wrote a more detailed version for others to read, and this is the last sentence of it.
-
-
-
-
-
-
-
-
-
-Notes
-
-[1] My experience skipped a step in the evolution of computers: time-sharing machines with interactive OSes. I went straight from batch processing to microcomputers, which made microcomputers seem all the more exciting.
-
-[2] Italian words for abstract concepts can nearly always be predicted from their English cognates (except for occasional traps like polluzione). It's the everyday words that differ. So if you string together a lot of abstract concepts with a few simple verbs, you can make a little Italian go a long way.
-
-[3] I lived at Piazza San Felice 4, so my walk to the Accademia went straight down the spine of old Florence: past the Pitti, across the bridge, past Orsanmichele, between the Duomo and the Baptistery, and then up Via Ricasoli to Piazza San Marco. I saw Florence at street level in every possible condition, from empty dark winter evenings to sweltering summer days when the streets were packed with tourists.
-
-[4] You can of course paint people like still lives if you want to, and they're willing. That sort of portrait is arguably the apex of still life painting, though the long sitting does tend to produce pained expressions in the sitters.
-
-[5] Interleaf was one of many companies that had smart people and built impressive technology, and yet got crushed by Moore's Law. In the 1990s the exponential growth in the power of commodity (i.e. Intel) processors rolled up high-end, special-purpose hardware and software companies like a bulldozer.
-
-[6] The signature style seekers at RISD weren't specifically mercenary. In the art world, money and coolness are tightly coupled. Anything expensive comes to be seen as cool, and anything seen as cool will soon become equally expensive.
-
-[7] Technically the apartment wasn't rent-controlled but rent-stabilized, but this is a refinement only New Yorkers would know or care about. The point is that it was really cheap, less than half market price.
-
-[8] Most software you can launch as soon as it's done. But when the software is an online store builder and you're hosting the stores, if you don't have any users yet, that fact will be painfully obvious. So before we could launch publicly we had to launch privately, in the sense of recruiting an initial set of users and making sure they had decent-looking stores.
-
-[9] We'd had a code editor in Viaweb for users to define their own page styles. They didn't know it, but they were editing Lisp expressions underneath. But this wasn't an app editor, because the code ran when the merchants' sites were generated, not when shoppers visited them.
-
-[10] This was the first instance of what is now a familiar experience, and so was what happened next, when I read the comments and found they were full of angry people. How could I claim that Lisp was better than other languages? Weren't they all Turing complete? People who see the responses to essays I write sometimes tell me how sorry they feel for me, but I'm not exaggerating when I reply that it has always been like this, since the very beginning. It comes with the territory. An essay must tell readers things they don't already know, and some people dislike being told such things.
-
-[11] People put plenty of stuff on the internet in the 90s of course, but putting something online is not the same as publishing it online. Publishing online means you treat the online version as the (or at least a) primary version.
-
-[12] There is a general lesson here that our experience with Y Combinator also teaches: Customs continue to constrain you long after the restrictions that caused them have disappeared. Customary VC practice had once, like the customs about publishing essays, been based on real constraints. Startups had once been much more expensive to start, and proportionally rare. Now they could be cheap and common, but the VCs' customs still reflected the old world, just as customs about writing essays still reflected the constraints of the print era.
-
-Which in turn implies that people who are independent-minded (i.e. less influenced by custom) will have an advantage in fields affected by rapid change (where customs are more likely to be obsolete).
-
-Here's an interesting point, though: you can't always predict which fields will be affected by rapid change. Obviously software and venture capital will be, but who would have predicted that essay writing would be?
-
-[13] Y Combinator was not the original name. At first we were called Cambridge Seed. But we didn't want a regional name, in case someone copied us in Silicon Valley, so we renamed ourselves after one of the coolest tricks in the lambda calculus, the Y combinator.
-
-I picked orange as our color partly because it's the warmest, and partly because no VC used it. In 2005 all the VCs used staid colors like maroon, navy blue, and forest green, because they were trying to appeal to LPs, not founders. The YC logo itself is an inside joke: the Viaweb logo had been a white V on a red circle, so I made the YC logo a white Y on an orange square.
-
-[14] YC did become a fund for a couple years starting in 2009, because it was getting so big I could no longer afford to fund it personally. But after Heroku got bought we had enough money to go back to being self-funded.
-
-[15] I've never liked the term "deal flow," because it implies that the number of new startups at any given time is fixed. This is not only false, but it's the purpose of YC to falsify it, by causing startups to be founded that would not otherwise have existed.
-
-[16] She reports that they were all different shapes and sizes, because there was a run on air conditioners and she had to get whatever she could, but that they were all heavier than she could carry now.
-
-[17] Another problem with HN was a bizarre edge case that occurs when you both write essays and run a forum. When you run a forum, you're assumed to see if not every conversation, at least every conversation involving you. And when you write essays, people post highly imaginative misinterpretations of them on forums. Individually these two phenomena are tedious but bearable, but the combination is disastrous. You actually have to respond to the misinterpretations, because the assumption that you're present in the conversation means that not responding to any sufficiently upvoted misinterpretation reads as a tacit admission that it's correct. But that in turn encourages more; anyone who wants to pick a fight with you senses that now is their chance.
-
-[18] The worst thing about leaving YC was not working with Jessica anymore. We'd been working on YC almost the whole time we'd known each other, and we'd neither tried nor wanted to separate it from our personal lives, so leaving was like pulling up a deeply rooted tree.
-
-[19] One way to get more precise about the concept of invented vs discovered is to talk about space aliens. Any sufficiently advanced alien civilization would certainly know about the Pythagorean theorem, for example. I believe, though with less certainty, that they would also know about the Lisp in McCarthy's 1960 paper.
-
-But if so there's no reason to suppose that this is the limit of the language that might be known to them. Presumably aliens need numbers and errors and I/O too. So it seems likely there exists at least one path out of McCarthy's Lisp along which discoveredness is preserved.
-
-
-
-Thanks to Trevor Blackwell, John Collison, Patrick Collison, Daniel Gackle, Ralph Hazell, Jessica Livingston, Robert Morris, and Harj Taggar for reading drafts of this.
\ No newline at end of file
diff --git a/tests/old_proxy_tests/tests/load_test_completion.py b/tests/old_proxy_tests/tests/load_test_completion.py
deleted file mode 100644
index afbd74a7900..00000000000
--- a/tests/old_proxy_tests/tests/load_test_completion.py
+++ /dev/null
@@ -1,68 +0,0 @@
-import time
-import asyncio
-import os
-from openai import AsyncOpenAI, AsyncAzureOpenAI
-from litellm._uuid import uuid
-import traceback
-from large_text import text
-from dotenv import load_dotenv
-from statistics import mean, median
-
-litellm_client = AsyncOpenAI(base_url="http://0.0.0.0:4000/", api_key="sk-1234")
-
-
-async def litellm_completion():
-    try:
-        start_time = time.time()
-        response = await litellm_client.chat.completions.create(
-            model="fake-openai-endpoint",
-            messages=[
-                {
-                    "role": "user",
-                    "content": f"This is a test{uuid.uuid4()}",
-                }
-            ],
-            user="my-new-end-user-1",
-        )
-        end_time = time.time()
-        latency = end_time - start_time
-        print("response time=", latency)
-        return response, latency
-
-    except Exception as e:
-        with open("error_log.txt", "a") as error_log:
-            error_log.write(f"Error during completion: {str(e)}\n")
-        return None, 0
-
-
-async def main():
-    latencies = []
-    for i in range(5):
-        start = time.time()
-        n = 100  # Number of concurrent tasks
-        tasks = [litellm_completion() for _ in range(n)]
-
-        chat_completions = await asyncio.gather(*tasks)
-
-        successful_completions = [c for c, l in chat_completions if c is not None]
-        completion_latencies = [l for c, l in chat_completions if c is not None]
-        latencies.extend(completion_latencies)
-
-        with open("error_log.txt", "a") as error_log:
-            for completion, latency in chat_completions:
-                if isinstance(completion, str):
-                    error_log.write(completion + "\n")
-
-        print(n, time.time() - start, len(successful_completions))
-
-    if latencies:
-        average_latency = mean(latencies)
-        median_latency = median(latencies)
-        print(f"Average Latency per Response: {average_latency} seconds")
-        print(f"Median Latency per Response: {median_latency} seconds")
-
-
-if __name__ == "__main__":
-    open("error_log.txt", "w").close()
-
-    asyncio.run(main())
diff --git a/tests/old_proxy_tests/tests/load_test_embedding.py b/tests/old_proxy_tests/tests/load_test_embedding.py
deleted file mode 100644
index c184879a39e..00000000000
--- a/tests/old_proxy_tests/tests/load_test_embedding.py
+++ /dev/null
@@ -1,107 +0,0 @@
-# test time it takes to make 100 concurrent embedding requests to OpenaI
-
-import os
-import sys
-import traceback
-
-from dotenv import load_dotenv
-
-load_dotenv()
-import io
-import os
-
-sys.path.insert(
-    0, os.path.abspath("../..")
-)  # Adds the parent directory to the system path
-import pytest
-
-import litellm
-
-litellm.set_verbose = False
-
-
-question = "embed this very long text" * 100
-
-
-# make X concurrent calls to litellm.completion(model=gpt-35-turbo, messages=[]), pick a random question in questions array.
-#  Allow me to tune X concurrent calls.. Log question, output/exception, response time somewhere
-# show me a summary of requests made, success full calls, failed calls. For failed calls show me the exceptions
-
-import concurrent.futures
-import random
-import time
-
-
-# Function to make concurrent calls to OpenAI API
-def make_openai_completion(question):
-    try:
-        time.time()
-        import openai
-
-        client = openai.OpenAI(
-            api_key=os.environ["OPENAI_API_KEY"]
-        )  # base_url="http://0.0.0.0:8000",
-        response = client.embeddings.create(
-            model="text-embedding-ada-002",
-            input=[question],
-        )
-        print(response)
-        time.time()
-
-        # Log the request details
-        # with open("request_log.txt", "a") as log_file:
-        #     log_file.write(
-        #         f"Question: {question[:100]}\nResponse ID:{response.id} Content:{response.choices[0].message.content[:10]}\nTime: {end_time - start_time:.2f} seconds\n\n"
-        #     )
-
-        return response
-    except Exception:
-        # Log exceptions for failed calls
-        # with open("error_log.txt", "a") as error_log_file:
-        #     error_log_file.write(
-        #         f"\nException: {str(e)}\n\n"
-        #     )
-        return None
-
-
-start_time = time.time()
-# Number of concurrent calls (you can adjust this)
-concurrent_calls = 500
-
-# List to store the futures of concurrent calls
-futures = []
-
-# Make concurrent calls
-with concurrent.futures.ThreadPoolExecutor(max_workers=concurrent_calls) as executor:
-    for _ in range(concurrent_calls):
-        futures.append(executor.submit(make_openai_completion, question))
-
-# Wait for all futures to complete
-concurrent.futures.wait(futures)
-
-# Summarize the results
-successful_calls = 0
-failed_calls = 0
-
-for future in futures:
-    if future.result() is not None:
-        successful_calls += 1
-    else:
-        failed_calls += 1
-
-end_time = time.time()
-# Calculate the duration
-duration = end_time - start_time
-
-print("Load test Summary:")
-print(f"Total Requests: {concurrent_calls}")
-print(f"Successful Calls: {successful_calls}")
-print(f"Failed Calls: {failed_calls}")
-print(f"Total Time: {duration:.2f} seconds")
-
-# Display content of the logs
-with open("request_log.txt", "r") as log_file:
-    print("\nRequest Log:\n", log_file.read())
-
-with open("error_log.txt", "r") as error_log_file:
-    print("\nError Log:\n", error_log_file.read())
diff --git a/tests/old_proxy_tests/tests/load_test_embedding_100.py b/tests/old_proxy_tests/tests/load_test_embedding_100.py
deleted file mode 100644
index 8cd4d250249..00000000000
--- a/tests/old_proxy_tests/tests/load_test_embedding_100.py
+++ /dev/null
@@ -1,54 +0,0 @@
-import time, asyncio
-from openai import AsyncOpenAI
-from litellm._uuid import uuid
-import traceback
-
-
-litellm_client = AsyncOpenAI(api_key="test", base_url="http://0.0.0.0:8000")
-
-
-async def litellm_completion():
-    # Your existing code for litellm_completion goes here
-    try:
-        print("starting embedding calls")
-        response = await litellm_client.embeddings.create(
-            model="text-embedding-ada-002",
-            input=[
-                "hello who are you" * 2000,
-                "hello who are you tomorrow 1234" * 1000,
-                "hello who are you tomorrow 1234" * 1000,
-            ],
-        )
-        print(response)
-        return response
-
-    except Exception as e:
-        # If there's an exception, log the error message
-        with open("error_log.txt", "a") as error_log:
-            error_log.write(f"Error during completion: {str(e)}\n")
-        pass
-
-
-async def main():
-    start = time.time()
-    n = 100  # Number of concurrent tasks
-    tasks = [litellm_completion() for _ in range(n)]
-
-    chat_completions = await asyncio.gather(*tasks)
-
-    successful_completions = [c for c in chat_completions if c is not None]
-
-    # Write errors to error_log.txt
-    with open("error_log.txt", "a") as error_log:
-        for completion in chat_completions:
-            if isinstance(completion, str):
-                error_log.write(completion + "\n")
-
-    print(n, time.time() - start, len(successful_completions))
-
-
-if __name__ == "__main__":
-    # Blank out contents of error_log.txt
-    open("error_log.txt", "w").close()
-
-    asyncio.run(main())
diff --git a/tests/old_proxy_tests/tests/load_test_embedding_proxy.py b/tests/old_proxy_tests/tests/load_test_embedding_proxy.py
deleted file mode 100644
index 24485a22064..00000000000
--- a/tests/old_proxy_tests/tests/load_test_embedding_proxy.py
+++ /dev/null
@@ -1,107 +0,0 @@
-# test time it takes to make 100 concurrent embedding requests to OpenaI
-
-import os
-import sys
-import traceback
-
-from dotenv import load_dotenv
-
-load_dotenv()
-import io
-import os
-
-sys.path.insert(
-    0, os.path.abspath("../..")
-)  # Adds the parent directory to the system path
-import pytest
-
-import litellm
-
-litellm.set_verbose = False
-
-
-question = "embed this very long text" * 100
-
-
-# make X concurrent calls to litellm.completion(model=gpt-35-turbo, messages=[]), pick a random question in questions array.
-#  Allow me to tune X concurrent calls.. Log question, output/exception, response time somewhere
-# show me a summary of requests made, success full calls, failed calls. For failed calls show me the exceptions
-
-import concurrent.futures
-import random
-import time
-
-
-# Function to make concurrent calls to OpenAI API
-def make_openai_completion(question):
-    try:
-        time.time()
-        import openai
-
-        client = openai.OpenAI(
-            api_key=os.environ["OPENAI_API_KEY"], base_url="http://0.0.0.0:8000"
-        )  # base_url="http://0.0.0.0:8000",
-        response = client.embeddings.create(
-            model="text-embedding-ada-002",
-            input=[question],
-        )
-        print(response)
-        time.time()
-
-        # Log the request details
-        # with open("request_log.txt", "a") as log_file:
-        #     log_file.write(
-        #         f"Question: {question[:100]}\nResponse ID:{response.id} Content:{response.choices[0].message.content[:10]}\nTime: {end_time - start_time:.2f} seconds\n\n"
-        #     )
-
-        return response
-    except Exception:
-        # Log exceptions for failed calls
-        # with open("error_log.txt", "a") as error_log_file:
-        #     error_log_file.write(
-        #         f"\nException: {str(e)}\n\n"
-        #     )
-        return None
-
-
-start_time = time.time()
-# Number of concurrent calls (you can adjust this)
-concurrent_calls = 500
-
-# List to store the futures of concurrent calls
-futures = []
-
-# Make concurrent calls
-with concurrent.futures.ThreadPoolExecutor(max_workers=concurrent_calls) as executor:
-    for _ in range(concurrent_calls):
-        futures.append(executor.submit(make_openai_completion, question))
-
-# Wait for all futures to complete
-concurrent.futures.wait(futures)
-
-# Summarize the results
-successful_calls = 0
-failed_calls = 0
-
-for future in futures:
-    if future.result() is not None:
-        successful_calls += 1
-    else:
-        failed_calls += 1
-end_time = time.time()
-# Calculate the duration
-duration = end_time - start_time
-
-
-print("Load test Summary:")
-print(f"Total Requests: {concurrent_calls}")
-print(f"Successful Calls: {successful_calls}")
-print(f"Failed Calls: {failed_calls}")
-print(f"Total Time: {duration:.2f} seconds")
-
-# # Display content of the logs
-# with open("request_log.txt", "r") as log_file:
-#     print("\nRequest Log:\n", log_file.read())
-
-# with open("error_log.txt", "r") as error_log_file:
-#     print("\nError Log:\n", error_log_file.read())
diff --git a/tests/old_proxy_tests/tests/load_test_q.py b/tests/old_proxy_tests/tests/load_test_q.py
deleted file mode 100644
index 89137c306a7..00000000000
--- a/tests/old_proxy_tests/tests/load_test_q.py
+++ /dev/null
@@ -1,121 +0,0 @@
-import os
-import time
-
-import requests
-from dotenv import load_dotenv
-
-load_dotenv()
-
-
-# Set the base URL as needed
-base_url = "https://api.litellm.ai"
-# # Uncomment the line below if you want to switch to the local server
-# base_url = "http://0.0.0.0:8000"
-
-# Step 1 Add a config to the proxy, generate a temp key
-config = {
-    "model_list": [
-        {
-            "model_name": "gpt-3.5-turbo",
-            "litellm_params": {
-                "model": "gpt-3.5-turbo",
-                "api_key": os.environ["OPENAI_API_KEY"],
-            },
-        },
-        {
-            "model_name": "gpt-3.5-turbo",
-            "litellm_params": {
-                "model": "azure/gpt-4.1-mini",
-                "api_key": os.environ["AZURE_AI_API_KEY"],
-                "api_base": "https://openai-gpt-4-test-v-1.openai.azure.com/",
-                "api_version": "2023-07-01-preview",
-            },
-        },
-    ]
-}
-print("STARTING LOAD TEST Q")
-print(os.environ["AZURE_AI_API_KEY"])
-
-response = requests.post(
-    url=f"{base_url}/key/generate",
-    json={
-        "config": config,
-        "duration": "30d",  # default to 30d, set it to 30m if you want a temp key
-    },
-    headers={"Authorization": "Bearer sk-hosted-litellm"},
-)
-
-print("\nresponse from generating key", response.text)
-print("\n json response from gen key", response.json())
-
-generated_key = response.json()["key"]
-print("\ngenerated key for proxy", generated_key)
-
-
-# Step 2: Queue 50 requests to the proxy, using your generated_key
-
-import concurrent.futures
-
-
-def create_job_and_poll(request_num):
-    print(f"Creating a job on the proxy for request {request_num}")
-    job_response = requests.post(
-        url=f"{base_url}/queue/request",
-        json={
-            "model": "gpt-3.5-turbo",
-            "messages": [
-                {"role": "system", "content": "write a short poem"},
-            ],
-        },
-        headers={"Authorization": f"Bearer {generated_key}"},
-    )
-    print(job_response.status_code)
-    print(job_response.text)
-    print("\nResponse from creating job", job_response.text)
-    job_response = job_response.json()
-    job_response["id"]
-    polling_url = job_response["url"]
-    polling_url = f"{base_url}{polling_url}"
-    print(f"\nCreated Job {request_num}, Polling Url {polling_url}")
-
-    # Poll each request
-    while True:
-        try:
-            print(f"\nPolling URL for request {request_num}", polling_url)
-            polling_response = requests.get(
-                url=polling_url, headers={"Authorization": f"Bearer {generated_key}"}
-            )
-            print(
-                f"\nResponse from polling url for request {request_num}",
-                polling_response.text,
-            )
-            polling_response = polling_response.json()
-            status = polling_response.get("status", None)
-            if status == "finished":
-                llm_response = polling_response["result"]
-                print(f"LLM Response for request {request_num}")
-                print(llm_response)
-                # Write the llm_response to load_test_log.txt
-                try:
-                    with open("load_test_log.txt", "a") as response_file:
-                        response_file.write(
-                            f"Response for request: {request_num}\n{llm_response}\n\n"
-                        )
-                except Exception as e:
-                    print("GOT EXCEPTION", e)
-                break
-            time.sleep(0.5)
-        except Exception as e:
-            print("got exception when polling", e)
-
-
-# Number of requests
-num_requests = 100
-
-# Use ThreadPoolExecutor for parallel execution
-with concurrent.futures.ThreadPoolExecutor(max_workers=num_requests) as executor:
-    # Create and poll each request in parallel
-    futures = [executor.submit(create_job_and_poll, i) for i in range(num_requests)]
-
-    # Wait for all futures to complete
-    concurrent.futures.wait(futures)
diff --git a/tests/old_proxy_tests/tests/request_log.txt b/tests/old_proxy_tests/tests/request_log.txt
deleted file mode 100644
index e69de29bb2d..00000000000
diff --git a/tests/old_proxy_tests/tests/test_anthropic_context_caching.py b/tests/old_proxy_tests/tests/test_anthropic_context_caching.py
deleted file mode 100644
index 6b37873df4e..00000000000
--- a/tests/old_proxy_tests/tests/test_anthropic_context_caching.py
+++ /dev/null
@@ -1,36 +0,0 @@
-import openai
-
-client = openai.OpenAI(
-    api_key="sk-1234",  # litellm proxy api key
-    base_url="http://0.0.0.0:4000",  # litellm proxy base url
-)
-
-
-response = client.chat.completions.create(
-    model="anthropic/claude-sonnet-4-5-20250929",
-    messages=[
-        {  # type: ignore
-            "role": "system",
-            "content": [
-                {
-                    "type": "text",
-                    "text": "You are an AI assistant tasked with analyzing legal documents.",
-                },
-                {
-                    "type": "text",
-                    "text": "Here is the full text of a complex legal agreement" * 100,
-                    "cache_control": {"type": "ephemeral"},
-                },
-            ],
-        },
-        {
-            "role": "user",
-            "content": "what are the key terms and conditions in this agreement?",
-        },
-    ],
-    extra_headers={
-        "anthropic-version": "2023-06-01",
-    },
-)
-
-print(response)
diff --git a/tests/old_proxy_tests/tests/test_anthropic_sdk.py b/tests/old_proxy_tests/tests/test_anthropic_sdk.py
deleted file mode 100644
index 289fc845549..00000000000
--- a/tests/old_proxy_tests/tests/test_anthropic_sdk.py
+++ /dev/null
@@ -1,22 +0,0 @@
-import os
-
-from anthropic import Anthropic
-
-client = Anthropic(
-    # This is the default and can be omitted
-    base_url="http://localhost:4000",
-    # this is a litellm proxy key :) - not a real anthropic key
-    api_key="sk-test-proxy-key-123",
-)
-
-message = client.messages.create(
-    max_tokens=1024,
-    messages=[
-        {
-            "role": "user",
-            "content": "Hello, Claude",
-        }
-    ],
-    model="claude-3-opus-20240229",
-)
-print(message.content)
diff --git a/tests/old_proxy_tests/tests/test_async.py b/tests/old_proxy_tests/tests/test_async.py
deleted file mode 100644
index 65d289853ba..00000000000
--- a/tests/old_proxy_tests/tests/test_async.py
+++ /dev/null
@@ -1,28 +0,0 @@
-# # This tests the litelm proxy
-# # it makes async Completion requests with streaming
-# import openai
-
-# openai.base_url = "http://0.0.0.0:8000"
-# openai.api_key = "temp-key"
-# print(openai.base_url)
-
-# async def test_async_completion():
-#     response = await (
-#         model="gpt-3.5-turbo",
-#         prompt='this is a test request, write a short poem',
-#     )
-#     print(response)
-
-#     print("test_streaming")
-#     response = await openai.chat.completions.create(
-#         model="gpt-3.5-turbo",
-#         prompt='this is a test request, write a short poem',
-#         stream=True
-#     )
-#     print(response)
-#     async for chunk in response:
-#         print(chunk)
-
-
-# import asyncio
-# asyncio.run(test_async_completion())
diff --git a/tests/old_proxy_tests/tests/test_gemini_context_caching.py b/tests/old_proxy_tests/tests/test_gemini_context_caching.py
deleted file mode 100644
index 6ee143dba16..00000000000
--- a/tests/old_proxy_tests/tests/test_gemini_context_caching.py
+++ /dev/null
@@ -1,54 +0,0 @@
-import datetime
-
-import httpx
-import openai
-
-# Set Litellm proxy variables here
-LITELLM_BASE_URL = "http://0.0.0.0:4000"
-LITELLM_PROXY_API_KEY = "sk-1234"
-
-client = openai.OpenAI(api_key=LITELLM_PROXY_API_KEY, base_url=LITELLM_BASE_URL)
-httpx_client = httpx.Client(timeout=30)
-
-################################
-# First create a cachedContents object
-print("creating cached content")
-create_cache = httpx_client.post(
-    url=f"{LITELLM_BASE_URL}/vertex-ai/cachedContents",
-    headers={"Authorization": f"Bearer {LITELLM_PROXY_API_KEY}"},
-    json={
-        "model": "gemini-1.5-pro-001",
-        "contents": [
-            {
-                "role": "user",
-                "parts": [
-                    {
-                        "text": "This is sample text to demonstrate explicit caching."
-                        * 4000
-                    }
-                ],
-            }
-        ],
-    },
-)
-print("response from create_cache", create_cache)
-create_cache_response = create_cache.json()
-print("json from create_cache", create_cache_response)
-cached_content_name = create_cache_response["name"]
-
-#################################
-# Use the `cachedContents` object in your /chat/completions
-response = client.chat.completions.create(  # type: ignore
-    model="gemini-1.5-pro-001",
-    max_tokens=8192,
-    messages=[
-        {
-            "role": "user",
-            "content": "what is the sample text about?",
-        },
-    ],
-    temperature="0.7",
-    extra_body={"cached_content": cached_content_name},  # 👈 key change
-)
-
-print("response from proxy", response)
diff --git a/tests/old_proxy_tests/tests/test_langchain_embedding.py b/tests/old_proxy_tests/tests/test_langchain_embedding.py
deleted file mode 100644
index 69ef541488c..00000000000
--- a/tests/old_proxy_tests/tests/test_langchain_embedding.py
+++ /dev/null
@@ -1,17 +0,0 @@
-from langchain_openai import OpenAIEmbeddings
-
-embeddings_models = "multimodalembedding@001"
-
-embeddings = OpenAIEmbeddings(
-    model="multimodalembedding@001",
-    base_url="http://0.0.0.0:4000",
-    api_key="sk-1234",  # type: ignore
-)
-
-
-query_result = embeddings.embed_query(
-    "gs://cloud-samples-data/vertex-ai/llm/prompts/landmark1.png"
-)
-# print(len(query_result))
-# print(query_result[:5])
-print(query_result)
diff --git a/tests/old_proxy_tests/tests/test_langchain_request.py b/tests/old_proxy_tests/tests/test_langchain_request.py
deleted file mode 100644
index dcbf94f8be0..00000000000
--- a/tests/old_proxy_tests/tests/test_langchain_request.py
+++ /dev/null
@@ -1,44 +0,0 @@
-# # LOCAL TEST
-# from langchain.chat_models import ChatOpenAI
-# from langchain.prompts.chat import (
-#     ChatPromptTemplate,
-#     HumanMessagePromptTemplate,
-#     SystemMessagePromptTemplate,
-# )
-# from langchain.schema import HumanMessage, SystemMessage
-
-# chat = ChatOpenAI(
-#     openai_api_base="http://0.0.0.0:8000",
-#     model = "azure/gpt-4.1-mini",
-#     temperature=0.1,
-#     extra_body={
-#         "metadata": {
-#             "generation_name": "ishaan-generation-langchain-client",
-#             "generation_id": "langchain-client-gen-id22",
-#             "trace_id": "langchain-client-trace-id22",
-#             "trace_user_id": "langchain-client-user-id2"
-#         }
-#     }
-# )
-
-# messages = [
-#     SystemMessage(
-#         content="You are a helpful assistant that im using to make a test request to."
-#     ),
-#     HumanMessage(
-#         content="test from litellm. tell me why it's amazing in 1 sentence"
-#     ),
-# ]
-# response = chat(messages)
-
-# print(response)
-
-# # claude_chat = ChatOpenAI(
-# #     openai_api_base="http://0.0.0.0:8000",
-# #     model = "claude-v1",
-# #     temperature=0.1
-# # )
-
-# # response = claude_chat(messages)
-
-# # print(response)
diff --git a/tests/old_proxy_tests/tests/test_llamaindex.py b/tests/old_proxy_tests/tests/test_llamaindex.py
deleted file mode 100644
index f5ae744e8d9..00000000000
--- a/tests/old_proxy_tests/tests/test_llamaindex.py
+++ /dev/null
@@ -1,36 +0,0 @@
-import os, dotenv
-
-from dotenv import load_dotenv
-
-load_dotenv()
-
-from llama_index.llms import AzureOpenAI
-from llama_index.embeddings import AzureOpenAIEmbedding
-from llama_index import VectorStoreIndex, SimpleDirectoryReader, ServiceContext
-
-llm = AzureOpenAI(
-    engine="azure-gpt-3.5",
-    temperature=0.0,
-    azure_endpoint="http://0.0.0.0:4000",
-    api_key="sk-1234",
-    api_version="2023-07-01-preview",
-)
-
-embed_model = AzureOpenAIEmbedding(
-    deployment_name="azure-embedding-model",
-    azure_endpoint="http://0.0.0.0:4000",
-    api_key="sk-1234",
-    api_version="2023-07-01-preview",
-)
-
-
-# response = llm.complete("The sky is a beautiful blue and")
-# print(response)
-
-documents = SimpleDirectoryReader("llama_index_data").load_data()
-service_context = ServiceContext.from_defaults(llm=llm, embed_model=embed_model)
-index = VectorStoreIndex.from_documents(documents, service_context=service_context)
-
-query_engine = index.as_query_engine()
-response = query_engine.query("What did the author do growing up?")
-print(response)
diff --git a/tests/old_proxy_tests/tests/test_mistral_sdk.py b/tests/old_proxy_tests/tests/test_mistral_sdk.py
deleted file mode 100644
index 0adc67b9381..00000000000
--- a/tests/old_proxy_tests/tests/test_mistral_sdk.py
+++ /dev/null
@@ -1,13 +0,0 @@
-import os
-
-from mistralai.client import MistralClient
-from mistralai.models.chat_completion import ChatMessage
-
-client = MistralClient(api_key="sk-1234", endpoint="http://0.0.0.0:4000")
-chat_response = client.chat(
-    model="mistral-small-latest",
-    messages=[
-        {"role": "user", "content": "this is a test request, write a short poem"}
-    ],
-)
-print(chat_response.choices[0].message.content)
diff --git a/tests/old_proxy_tests/tests/test_openai_embedding.py b/tests/old_proxy_tests/tests/test_openai_embedding.py
deleted file mode 100644
index 3763f4edd75..00000000000
--- a/tests/old_proxy_tests/tests/test_openai_embedding.py
+++ /dev/null
@@ -1,126 +0,0 @@
-import openai
-import asyncio
-
-
-async def async_request(client, model, input_data):
-    response = await client.embeddings.create(model=model, input=input_data)
-    response = response.dict()
-    data_list = response["data"]
-    for i, embedding in enumerate(data_list):
-        embedding["embedding"] = []
-        current_index = embedding["index"]
-        assert i == current_index
-    return response
-
-
-async def main():
-    client = openai.AsyncOpenAI(api_key="sk-1234", base_url="http://0.0.0.0:4000")
-    models = [
-        "text-embedding-ada-002",
-        "text-embedding-ada-002",
-        "text-embedding-ada-002",
-    ]
-    inputs = [
-        [
-            "5",
-            "6",
-            "7",
-            "8",
-            "9",
-            "10",
-            "11",
-            "12",
-            "13",
-            "14",
-            "15",
-            "16",
-            "17",
-            "18",
-            "19",
-            "20",
-        ],
-        ["1", "2", "3", "4", "5", "6"],
-        [
-            "1",
-            "2",
-            "3",
-            "4",
-            "5",
-            "6",
-            "7",
-            "8",
-            "9",
-            "10",
-            "11",
-            "12",
-            "13",
-            "14",
-            "15",
-            "16",
-            "17",
-            "18",
-            "19",
-            "20",
-        ],
-        [
-            "1",
-            "2",
-            "3",
-            "4",
-            "5",
-            "6",
-            "7",
-            "8",
-            "9",
-            "10",
-            "11",
-            "12",
-            "13",
-            "14",
-            "15",
-            "16",
-            "17",
-            "18",
-            "19",
-            "20",
-        ],
-        [
-            "1",
-            "2",
-            "3",
-            "4",
-            "5",
-            "6",
-            "7",
-            "8",
-            "9",
-            "10",
-            "11",
-            "12",
-            "13",
-            "14",
-            "15",
-            "16",
-            "17",
-            "18",
-            "19",
-            "20",
-        ],
-        ["1", "2", "3"],
-    ]
-
-    tasks = []
-    for model, input_data in zip(models, inputs):
-        task = async_request(client, model, input_data)
-        tasks.append(task)
-
-    responses = await asyncio.gather(*tasks)
-    print(responses)
-    for response in responses:
-        data_list = response["data"]
-        for embedding in data_list:
-            embedding["embedding"] = []
-        print(response)
-
-
-asyncio.run(main())
diff --git a/tests/old_proxy_tests/tests/test_openai_exception_request.py b/tests/old_proxy_tests/tests/test_openai_exception_request.py
deleted file mode 100644
index 68b89977663..00000000000
--- a/tests/old_proxy_tests/tests/test_openai_exception_request.py
+++ /dev/null
@@ -1,53 +0,0 @@
-import openai
-import httpx
-import os
-from dotenv import load_dotenv
-
-load_dotenv()
-client = openai.OpenAI(
-    api_key="anything",
-    base_url="http://0.0.0.0:8000",
-    http_client=httpx.Client(verify=False),
-)
-
-try:
-    # request sent to model set on litellm proxy, `litellm --model`
-    response = client.chat.completions.create(
-        model="azure-gpt-3.5",
-        messages=[
-            {
-                "role": "user",
-                "content": "this is a test request, write a short poem" * 2000,
-            }
-        ],
-    )
-
-    print(response)
-except Exception as e:
-    print(e)
-    variables_proxy_exception = vars(e)
-    print("proxy exception variables", variables_proxy_exception.keys())
-    print(variables_proxy_exception["body"])
-
-
-api_key = os.getenv("AZURE_API_KEY")
-azure_endpoint = os.getenv("AZURE_API_BASE")
-print(api_key, azure_endpoint)
-client = openai.AzureOpenAI(
-    api_key=os.getenv("AZURE_API_KEY"),
-    azure_endpoint=os.getenv("AZURE_API_BASE", "default"),
-)
-try:
-    response = client.chat.completions.create(
-        model="chatgpt-v-3",
-        messages=[
-            {
-                "role": "user",
-                "content": "this is a test request, write a short poem" * 2000,
-            }
-        ],
-    )
-except Exception as e:
-    print(e)
-    variables_exception = vars(e)
-    print("openai client exception variables", variables_exception.keys())
diff --git a/tests/old_proxy_tests/tests/test_openai_js.js b/tests/old_proxy_tests/tests/test_openai_js.js
deleted file mode 100644
index 3fba873c245..00000000000
--- a/tests/old_proxy_tests/tests/test_openai_js.js
+++ /dev/null
@@ -1,41 +0,0 @@
-const openai = require('openai');
-
-// set DEBUG=true in env
-process.env.DEBUG=false;
-async function runOpenAI() {
-  const client = new openai.OpenAI({
-    apiKey: 'sk-1234',
-    baseURL: 'http://0.0.0.0:4000'
-  });
-
-
-
-  try {
-    const response = await client.chat.completions.create({
-      model: 'anthropic-claude-v2.1',
-      stream: true,
-      messages: [
-        {
-          role: 'user',
-          content: 'write a 20 pg essay about YC '.repeat(6000),
-        },
-      ],
-    });
-
-    console.log(response);
-    let original = '';
-    for await (const chunk of response) {
-      original += chunk.choices[0].delta.content;
-      console.log(original);
-      console.log(chunk);
-      console.log(chunk.choices[0].delta.content);
-    }
-  } catch (error) {
-    console.log("got this exception from server");
-    console.error(error);
-    console.log("done with exception from proxy");
-  }
-}
-
-// Call the asynchronous function
-runOpenAI();
\ No newline at end of file
diff --git a/tests/old_proxy_tests/tests/test_openai_request.py b/tests/old_proxy_tests/tests/test_openai_request.py
deleted file mode 100644
index 7c094e67ca5..00000000000
--- a/tests/old_proxy_tests/tests/test_openai_request.py
+++ /dev/null
@@ -1,60 +0,0 @@
-import openai
-
-client = openai.OpenAI(api_key="hi", base_url="http://0.0.0.0:8000")
-
-# # request sent to model set on litellm proxy, `litellm --model`
-response = client.chat.completions.create(
-    model="azure/gpt-4.1-mini",
-    messages=[
-        {"role": "user", "content": "this is a test request, write a short poem"}
-    ],
-    extra_body={
-        "metadata": {
-            "generation_name": "ishaan-generation-openai-client",
-            "generation_id": "openai-client-gen-id22",
-            "trace_id": "openai-client-trace-id22",
-            "trace_user_id": "openai-client-user-id2",
-        }
-    },
-)
-
-print(response)
-
-
-# request sent to gpt-4-vision + enhancements
-
-completion_extensions = client.chat.completions.create(
-    model="gpt-vision",
-    messages=[
-        {
-            "role": "user",
-            "content": [
-                {
-                    "type": "text",
-                    "text": "What's in this image? Output your answer in JSON.",
-                },
-                {
-                    "type": "image_url",
-                    "image_url": {
-                        "url": "https://avatars.githubusercontent.com/u/29436595?v=4",
-                        "detail": "low",
-                    },
-                },
-            ],
-        }
-    ],
-    max_tokens=4096,
-    temperature=0.0,
-    extra_body={
-        "enhancements": {"ocr": {"enabled": True}, "grounding": {"enabled": True}},
-        "dataSources": [
-            {
-                "type": "AzureComputerVision",
-                "parameters": {
-                    "endpoint": "https://gpt-4-vision-enhancement.cognitiveservices.azure.com/",
-                    "key": "f015cf8eeb1d4bd1b1467d21dec6063b",
-                },
-            }
-        ],
-    },
-)
diff --git a/tests/old_proxy_tests/tests/test_openai_request_with_traceparent.py b/tests/old_proxy_tests/tests/test_openai_request_with_traceparent.py
deleted file mode 100644
index 2f8455dcbe9..00000000000
--- a/tests/old_proxy_tests/tests/test_openai_request_with_traceparent.py
+++ /dev/null
@@ -1,41 +0,0 @@
-# mypy: ignore-errors
-import openai
-from opentelemetry import trace
-from opentelemetry.context import Context
-from opentelemetry.trace import SpanKind
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import SimpleSpanProcessor
-from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
-from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
-
-
-trace.set_tracer_provider(TracerProvider())
-memory_exporter = InMemorySpanExporter()
-span_processor = SimpleSpanProcessor(memory_exporter)
-trace.get_tracer_provider().add_span_processor(span_processor)
-tracer = trace.get_tracer(__name__)
-
-# create an otel traceparent header
-tracer = trace.get_tracer(__name__)
-with tracer.start_as_current_span("ishaan-local-dev-app") as span:
-    span.set_attribute("generation_name", "ishaan-generation-openai-client")
-    client = openai.OpenAI(api_key="sk-1234", base_url="http://0.0.0.0:4000")
-    extra_headers = {}
-    context = trace.set_span_in_context(span)
-    traceparent = TraceContextTextMapPropagator()
-    traceparent.inject(carrier=extra_headers, context=context)
-    print("EXTRA HEADERS: ", extra_headers)
-    _trace_parent = extra_headers.get("traceparent")
-    trace_id = _trace_parent.split("-")[1]
-    print("Trace ID: ", trace_id)
-
-    # # request sent to model set on litellm proxy, `litellm --model`
-    response = client.chat.completions.create(
-        model="llama3",
-        messages=[
-            {"role": "user", "content": "this is a test request, write a short poem"}
-        ],
-        extra_headers=extra_headers,
-    )
-
-    print(response)
diff --git a/tests/old_proxy_tests/tests/test_openai_simple_embedding.py b/tests/old_proxy_tests/tests/test_openai_simple_embedding.py
deleted file mode 100644
index 7dd38c0b396..00000000000
--- a/tests/old_proxy_tests/tests/test_openai_simple_embedding.py
+++ /dev/null
@@ -1,10 +0,0 @@
-import openai
-
-client = openai.OpenAI(api_key="sk-1234", base_url="http://0.0.0.0:4000")
-
-# # request sent to model set on litellm proxy, `litellm --model`
-response = client.embeddings.create(
-    model="text-embedding-ada-002", input=["test"], encoding_format="base64"
-)
-
-print(response)
diff --git a/tests/old_proxy_tests/tests/test_openai_tts_request.py b/tests/old_proxy_tests/tests/test_openai_tts_request.py
deleted file mode 100644
index 91848947aec..00000000000
--- a/tests/old_proxy_tests/tests/test_openai_tts_request.py
+++ /dev/null
@@ -1,11 +0,0 @@
-import openai
-
-client = openai.OpenAI(api_key="sk-1234", base_url="http://0.0.0.0:4000")
-
-# # request sent to model set on litellm proxy, `litellm --model`
-response = client.audio.speech.create(
-    model="vertex-tts",
-    input="the quick brown fox jumped over the lazy dogs",
-    voice={"languageCode": "en-US", "name": "en-US-Studio-O"},  # type: ignore
-)
-print("response from proxy", response)  # noqa
diff --git a/tests/old_proxy_tests/tests/test_pass_through_langfuse.py b/tests/old_proxy_tests/tests/test_pass_through_langfuse.py
deleted file mode 100644
index dfc91ee1b10..00000000000
--- a/tests/old_proxy_tests/tests/test_pass_through_langfuse.py
+++ /dev/null
@@ -1,14 +0,0 @@
-from langfuse import Langfuse
-
-langfuse = Langfuse(
-    host="http://localhost:4000",
-    public_key="anything",
-    secret_key="anything",
-)
-
-print("sending langfuse trace request")
-trace = langfuse.trace(name="test-trace-litellm-proxy-passthrough")
-print("flushing langfuse request")
-langfuse.flush()
-
-print("flushed langfuse request")
diff --git a/tests/old_proxy_tests/tests/test_q.py b/tests/old_proxy_tests/tests/test_q.py
deleted file mode 100644
index c95dfd57841..00000000000
--- a/tests/old_proxy_tests/tests/test_q.py
+++ /dev/null
@@ -1,85 +0,0 @@
-import os
-import time
-
-import requests
-from dotenv import load_dotenv
-
-load_dotenv()
-
-
-# Set the base URL as needed
-base_url = "https://api.litellm.ai"
-# Uncomment the line below if you want to switch to the local server
-# base_url = "http://0.0.0.0:8000"
-
-# Step 1 Add a config to the proxy, generate a temp key
-config = {
-    "model_list": [
-        {
-            "model_name": "gpt-3.5-turbo",
-            "litellm_params": {
-                "model": "gpt-3.5-turbo",
-                "api_key": os.environ["OPENAI_API_KEY"],
-            },
-        }
-    ]
-}
-
-response = requests.post(
-    url=f"{base_url}/key/generate",
-    json={
-        "config": config,
-        "duration": "30d",  # default to 30d, set it to 30m if you want a temp key
-    },
-    headers={"Authorization": "Bearer sk-hosted-litellm"},
-)
-
-print("\nresponse from generating key", response.text)
-print("\n json response from gen key", response.json())
-
-generated_key = response.json()["key"]
-print("\ngenerated key for proxy", generated_key)
-
-# Step 2: Queue a request to the proxy, using your generated_key
-print("Creating a job on the proxy")
-job_response = requests.post(
-    url=f"{base_url}/queue/request",
-    json={
-        "model": "gpt-3.5-turbo",
-        "messages": [
-            {
-                "role": "system",
-                "content": "You are a helpful assistant. What is your name",
-            },
-        ],
-    },
-    headers={"Authorization": f"Bearer {generated_key}"},
-)
-print(job_response.status_code)
-print(job_response.text)
-print("\nResponse from creating job", job_response.text)
-job_response = job_response.json()
-job_id = job_response["id"]  # type: ignore
-polling_url = job_response["url"]  # type: ignore
-polling_url = f"{base_url}{polling_url}"
-print("\nCreated Job, Polling Url", polling_url)
-
-# Step 3: Poll the request
-while True:
-    try:
-        print("\nPolling URL", polling_url)
-        polling_response = requests.get(
-            url=polling_url, headers={"Authorization": f"Bearer {generated_key}"}
-        )
-        print("\nResponse from polling url", polling_response.text)
-        polling_response = polling_response.json()
-        status = polling_response.get("status", None)  # type: ignore
-        if status == "finished":
-            llm_response = polling_response["result"]  # type: ignore
-            print("LLM Response")
-            print(llm_response)
-            break
-        time.sleep(0.5)
-    except Exception as e:
-        print("got exception in polling", e)
-        break
diff --git a/tests/old_proxy_tests/tests/test_simple_traceparent_openai.py b/tests/old_proxy_tests/tests/test_simple_traceparent_openai.py
deleted file mode 100644
index d4c36029948..00000000000
--- a/tests/old_proxy_tests/tests/test_simple_traceparent_openai.py
+++ /dev/null
@@ -1,22 +0,0 @@
-# mypy: ignore-errors
-from litellm._uuid import uuid
-
-import openai
-
-client = openai.OpenAI(api_key="sk-1234", base_url="http://0.0.0.0:4000")
-example_traceparent = "00-80e1afed08e019fc1110464cfa66635c-02e80198930058d4-01"
-extra_headers = {"traceparent": example_traceparent}
-_trace_id = example_traceparent.split("-")[1]
-
-print("EXTRA HEADERS: ", extra_headers)
-print("Trace ID: ", _trace_id)
-
-response = client.chat.completions.create(
-    model="llama3",
-    messages=[
-        {"role": "user", "content": "this is a test request, write a short poem"}
-    ],
-    extra_headers=extra_headers,
-)
-
-print(response)
diff --git a/tests/old_proxy_tests/tests/test_vertex_sdk_forward_headers.py b/tests/old_proxy_tests/tests/test_vertex_sdk_forward_headers.py
deleted file mode 100644
index f236e3f81a9..00000000000
--- a/tests/old_proxy_tests/tests/test_vertex_sdk_forward_headers.py
+++ /dev/null
@@ -1,52 +0,0 @@
-# import datetime
-
-# import vertexai
-# from vertexai.generative_models import Part
-# from vertexai.preview import caching
-# from vertexai.preview.generative_models import GenerativeModel
-
-# LITE_LLM_ENDPOINT = "http://localhost:4000"
-
-# vertexai.init(
-#     project="pathrise-convert-1606954137718",
-#     location="us-central1",
-#     api_endpoint=f"{LITE_LLM_ENDPOINT}/vertex-ai",
-#     api_transport="rest",
-# )
-
-# # model = GenerativeModel(model_name="gemini-1.5-flash-001")
-# # response = model.generate_content(
-# #     "hi tell me a joke and a very long story", stream=True
-# # )
-
-# # print("response", response)
-
-# # for chunk in response:
-# #     print(chunk)
-
-
-# system_instruction = """
-# You are an expert researcher. You always stick to the facts in the sources provided, and never make up new facts.
-# Now look at these research papers, and answer the following questions.
-# """
-
-# contents = [
-#     Part.from_uri(
-#         "gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf",
-#         mime_type="application/pdf",
-#     ),
-#     Part.from_uri(
-#         "gs://cloud-samples-data/generative-ai/pdf/2403.05530.pdf",
-#         mime_type="application/pdf",
-#     ),
-# ]
-
-# cached_content = caching.CachedContent.create(
-#     model_name="gemini-1.5-pro-001",
-#     system_instruction=system_instruction,
-#     contents=contents,
-#     ttl=datetime.timedelta(minutes=60),
-#     # display_name="example-cache",
-# )
-
-# print(cached_content.name)
diff --git a/tests/old_proxy_tests/tests/test_vtx_embedding.py b/tests/old_proxy_tests/tests/test_vtx_embedding.py
deleted file mode 100644
index 4c770ae2e9d..00000000000
--- a/tests/old_proxy_tests/tests/test_vtx_embedding.py
+++ /dev/null
@@ -1,21 +0,0 @@
-import openai
-
-client = openai.OpenAI(api_key="sk-1234", base_url="http://0.0.0.0:4000")
-
-# # request sent to model set on litellm proxy, `litellm --model`
-response = client.embeddings.create(
-    model="multimodalembedding@001",
-    input=[],
-    extra_body={
-        "instances": [
-            {
-                "image": {
-                    "gcsUri": "gs://cloud-samples-data/vertex-ai/llm/prompts/landmark1.png"
-                },
-                "text": "this is a unicorn",
-            },
-        ],
-    },
-)
-
-print(response)
diff --git a/tests/old_proxy_tests/tests/test_vtx_sdk_embedding.py b/tests/old_proxy_tests/tests/test_vtx_sdk_embedding.py
deleted file mode 100644
index a71718a204a..00000000000
--- a/tests/old_proxy_tests/tests/test_vtx_sdk_embedding.py
+++ /dev/null
@@ -1,58 +0,0 @@
-import vertexai
-from google.auth.credentials import Credentials
-from vertexai.vision_models import (
-    Image,
-    MultiModalEmbeddingModel,
-    Video,
-    VideoSegmentConfig,
-)
-
-LITELLM_PROXY_API_KEY = "sk-1234"
-LITELLM_PROXY_BASE = "http://0.0.0.0:4000/vertex-ai"
-
-import datetime
-
-
-class CredentialsWrapper(Credentials):
-    def __init__(self, token=None):
-        super().__init__()
-        self.token = token
-        self.expiry = None  # or set to a future date if needed
-
-    def refresh(self, request):
-        pass
-
-    def apply(self, headers, token=None):
-        headers["Authorization"] = f"Bearer {self.token}"
-
-    @property
-    def expired(self):
-        return False  # Always consider the token as non-expired
-
-    @property
-    def valid(self):
-        return True  # Always consider the credentials as valid
-
-
-credentials = CredentialsWrapper(token=LITELLM_PROXY_API_KEY)
-
-vertexai.init(
-    project="litellm-ci-cd",
-    location="us-central1",
-    api_endpoint=LITELLM_PROXY_BASE,
-    credentials=credentials,
-    api_transport="rest",
-)
-
-model = MultiModalEmbeddingModel.from_pretrained("multimodalembedding")
-image = Image.load_from_file(
-    "gs://cloud-samples-data/vertex-ai/llm/prompts/landmark1.png"
-)
-
-embeddings = model.get_embeddings(
-    image=image,
-    contextual_text="Colosseum",
-    dimension=1408,
-)
-print(f"Image Embedding: {embeddings.image_embedding}")
-print(f"Text Embedding: {embeddings.text_embedding}")

From ffab5a39d04725ffce7bd55732f42c0fbaa04cc4 Mon Sep 17 00:00:00 2001
From: yuneng-jiang <yuneng@berri.ai>
Date: Thu, 20 Aug 2026 10:08:49 -0700
Subject: [PATCH 32/35] feat(ci): ratchet the test suite's zero-assert,
 mock-echo and global-state debt (#37588)

* feat(ci): ratchet the test suite's zero-assert, mock-echo and global-state debt

The suite's dominant failure mode is tests that cannot fail for the reason anyone
would want them to. The testing-strategy audit measured five shapes of it, and
nothing mechanical stops any of them from reproducing, so they keep reproducing.

`scripts/check_test_quality.py` is an AST checker for those five, emitting the
same `path:line: CODE message` contract as `scripts/check_type_discipline.py`:

  TQ001  a collectible test with no assertion of any kind
  TQ002  mock-echo, where every assertion only inspects the mock that was patched
  TQ003  sys.path.insert inside the test tree
  TQ004  raw `os.environ[...] =`, which leaks into whatever runs next
  TQ005  `litellm.<attr> =`, the process-wide leak the 491-line conftest undoes

`scripts/test_quality_gate.py` caps each rule against test-quality-budget.json,
seeded at exactly today's count, and fails only when a rule is both over its
limit and higher than the base being merged into, so a change is blamed for what
it adds and never for drift already in the base. `--update` lowers a limit by
what a branch cleared, so the ceilings only ever fall. It runs in the existing
required lint job, which means it enforces without a ruleset change.

TQ001 follows assertions into helpers defined in the same module, transitively.
Without that it flagged 111 tests in tests/e2e, the harness this program holds up
as the reference, because that suite factors its assertions into shared helpers
(`assert_auth_denied(result, ...)`). Following them leaves 25, all of which reach
their assertions across a module boundary; those are grandfathered and documented
rather than papered over.

The seeded counts land within about 10% of the audit's independent numbers for
every rule measured on the same subtree, which is the cross-check that the
definitions here match the ones the audit pinned.

* fix(ci): resolve test helpers per scope, not by bare name

The helper walk keyed every function in a module by its bare name, so two
same-named helpers in different classes collided and the last one parsed won.
A test calling `self._check()` could be cleared by a `_check` belonging to a
different class, or flagged because of one.

Resolution is now scoped: a bare name looks up the module-level functions, and
`self.<name>` looks up the enclosing class's own methods and no other class's.
Recursion is tracked by function identity rather than by name, so the cycle
guard cannot be confused by the same collision.

This surfaced one real zero-assert test that a same-named helper elsewhere had
been clearing, so TQ001 seeds at 750 rather than 749.

The test module has to register itself in sys.modules before exec_module:
`@dataclass(slots=True)` rebuilds its class through `sys.modules[__module__]`,
and Scope fails to construct without it. Recorded at the call site, since it
reads like avoidable global mutation otherwise.

* fix: register test-quality-budget.json with the ratchet alarm

The repo keeps one census over its budget files: every *-budget.json on disk
must appear in DEFAULT_BUDGETS, or its ceilings can be raised with no signal.
tests/test_litellm/test_budget_ratchet_check.py asserts that set equality and
caught the new budget on the way in.

Registering it also turns the alarm on for TQ001-TQ005, so a later PR cannot
quietly raise a test-quality ceiling. The file already uses the {limit: N}
schema the ratchet reads, so no other change was needed.
---
 .github/workflows/test-linting.yml            |   5 +
 Makefile                                      |  18 +-
 scripts/budget_ratchet_check.py               |   1 +
 scripts/check_test_quality.py                 | 492 ++++++++++++++++++
 scripts/test_quality_gate.py                  | 289 ++++++++++
 test-quality-budget.json                      |  17 +
 tests/test_litellm/test_check_test_quality.py | 307 +++++++++++
 tests/test_litellm/test_test_quality_gate.py  | 125 +++++
 8 files changed, 1250 insertions(+), 4 deletions(-)
 create mode 100644 scripts/check_test_quality.py
 create mode 100644 scripts/test_quality_gate.py
 create mode 100644 test-quality-budget.json
 create mode 100644 tests/test_litellm/test_check_test_quality.py
 create mode 100644 tests/test_litellm/test_test_quality_gate.py

diff --git a/.github/workflows/test-linting.yml b/.github/workflows/test-linting.yml
index 7a0ae0faaa0..6acb4e93899 100644
--- a/.github/workflows/test-linting.yml
+++ b/.github/workflows/test-linting.yml
@@ -132,6 +132,11 @@ jobs:
         run: |
           uv run --no-sync python scripts/type_discipline_gate.py --base "$GATE_BASE_SHA"
 
+      - name: Check test-quality budget (zero-assert / mock-echo tests, sys.path.insert, raw env writes, litellm global mutation, delta vs base)
+        if: steps.changes.outputs.decision != 'skip'
+        run: |
+          uv run --no-sync python scripts/test_quality_gate.py --base "$GATE_BASE_SHA"
+
       - name: Print OpenAI version
         if: steps.changes.outputs.decision != 'skip'
         run: |
diff --git a/Makefile b/Makefile
index 6c125268678..c80f147bf49 100644
--- a/Makefile
+++ b/Makefile
@@ -7,6 +7,7 @@
 	info lint lint-inner lint-dev lint-checks format \
 	lint-basedpyright lint-e2e-basedpyright lint-basedpyright-budget-update lint-type-discipline lint-type-discipline-budget-update \
 	lint-ruff-budget lint-ruff-budget-update lint-budget-update lint-gate \
+	lint-test-quality lint-test-quality-budget-update \
 	install-dev install-proxy-dev install-test-deps install-hooks \
 	install-helm-unittest check-circular-imports check-import-safety check check-inner pre-commit \
 	lint-install lint-fetch-base bootstrap
@@ -35,7 +36,8 @@ help:
 	@echo "  make lint-ruff-budget - Gate the codebase total of each strict ruff rule against its limit"
 	@echo "  make lint-gate        - Strict ruff gate in CI-parity mode (fetches staging, simulates the merge)"
 	@echo "  make lint-ruff-budget-update - Ratchet ruff-strict-budget.json limits down by what this branch fixed"
-	@echo "  make lint-budget-update - Ratchet all budgets down (ruff + type-discipline + basedpyright)"
+	@echo "  make lint-test-quality  - Gate the test suite against test-quality-budget.json"
+	@echo "  make lint-budget-update - Ratchet all budgets down (ruff + type-discipline + test quality + basedpyright)"
 	@echo "  make check-circular-imports - Check for circular imports"
 	@echo "  make check-import-safety - Check import safety"
 	@echo "  make test               - Run all tests"
@@ -200,6 +202,11 @@ lint-e2e-basedpyright: $(LINT_E2E_DEP_INSTALL)
 lint-type-discipline: $(LINT_DEP_INSTALL) $(LINT_DEP_BASE)
 	$(UV_RUN) python scripts/type_discipline_gate.py --base origin/litellm_internal_staging
 
+# Test-quality budget (zero-assert / mock-echo tests, sys.path.insert, raw env writes,
+# litellm module-global mutation), counted across tests/ the same delta-vs-base way.
+lint-test-quality: $(LINT_DEP_INSTALL) $(LINT_DEP_BASE)
+	$(UV_RUN) python scripts/test_quality_gate.py --base origin/litellm_internal_staging
+
 # --update lowers each limit by what this branch fixed since its branch point, so
 # it needs the base ref fetched to resolve the merge-base.
 lint-basedpyright-budget-update: install-dev lint-fetch-base
@@ -221,8 +228,11 @@ lint-ruff-budget-update: install-dev lint-fetch-base
 lint-type-discipline-budget-update: install-dev lint-fetch-base
 	$(UV_RUN) python scripts/type_discipline_gate.py --update
 
-# Ratchet all budgets in one shot (ruff strict + type-discipline + basedpyright)
-lint-budget-update: lint-ruff-budget-update lint-type-discipline-budget-update lint-basedpyright-budget-update
+lint-test-quality-budget-update: install-dev lint-fetch-base
+	$(UV_RUN) python scripts/test_quality_gate.py --update
+
+# Ratchet all budgets in one shot (ruff strict + type-discipline + test quality + basedpyright)
+lint-budget-update: lint-ruff-budget-update lint-type-discipline-budget-update lint-test-quality-budget-update lint-basedpyright-budget-update
 
 check-circular-imports: $(LINT_DEP_INSTALL)
 	cd litellm && $(UV_RUN) python ../tests/documentation_tests/test_circular_imports.py && cd ..
@@ -244,7 +254,7 @@ lint:
 lint-inner: lint-install lint-fetch-base
 	$(MAKE) -j $(LINT_JOBS) $(LINT_OUTPUT_SYNC) LINT_DEP_INSTALL= LINT_E2E_DEP_INSTALL= LINT_DEP_BASE= lint-checks
 
-lint-checks: lint-format-check-changed lint-ruff lint-gate lint-type-discipline lint-basedpyright lint-e2e-basedpyright check-circular-imports check-import-safety
+lint-checks: lint-format-check-changed lint-ruff lint-gate lint-type-discipline lint-test-quality lint-basedpyright lint-e2e-basedpyright check-circular-imports check-import-safety
 
 # Faster linting for local development (only checks changed code)
 lint-dev: lint-format-changed check-circular-imports check-import-safety
diff --git a/scripts/budget_ratchet_check.py b/scripts/budget_ratchet_check.py
index e97cd1bca00..34dd234477a 100644
--- a/scripts/budget_ratchet_check.py
+++ b/scripts/budget_ratchet_check.py
@@ -44,6 +44,7 @@ DEFAULT_BUDGETS: tuple[str, ...] = (
     "ruff-strict-budget.json",
     "type-discipline-budget.json",
     "basedpyright-code-budget.json",
+    "test-quality-budget.json",
 )
 GRADUATION_CONFIGS = MappingProxyType({"ruff-strict-budget.json": "ruff.toml"})
 
diff --git a/scripts/check_test_quality.py b/scripts/check_test_quality.py
new file mode 100644
index 00000000000..dd1e6b97c59
--- /dev/null
+++ b/scripts/check_test_quality.py
@@ -0,0 +1,492 @@
+#!/usr/bin/env python3
+"""Test-quality checker: the test-suite smells no linter enforces.
+
+Sibling of scripts/check_type_discipline.py, same output contract
+(``path:line: CODE message``) and same stdlib-only constraint, aimed at the test
+tree instead of the package. Each rule is a shape the testing-strategy audit
+measured and named; scripts/test_quality_gate.py caps the codebase total of each
+one against test-quality-budget.json so the counts can only ratchet down.
+
+Rules
+-----
+TQ001   A collectible test function whose body contains no assertion of any kind:
+        no `assert` statement, no `pytest.raises`/`warns`/`deprecated_call`/`fail`,
+        and no `assert*` method call (mock's `assert_called_once`, unittest's
+        `assertEqual`, `numpy.testing.assert_allclose`). Such a test passes as long
+        as the code under it does not raise, so it pins nothing and cannot fail for
+        the reason anyone would want it to. Assert the observable output instead.
+        The whole function subtree counts, nested helper definitions included, so a
+        test that asserts inside a locally-defined async helper passes.
+TQ002   Mock-echo: a test that patches something and whose every assertion only
+        inspects the mock that replaced it (`assert_called_once_with`, `.called`,
+        `.call_args`, `.call_count`, `.mock_calls`). The test restates the
+        implementation back at itself: it verifies that the code called what the
+        code calls, so it survives any refactor that keeps the call and breaks the
+        behavior. Assert what the caller observes -- the returned value, the
+        rebuilt response, the raised exception -- and fake at the HTTP boundary
+        (respx / MockTransport) rather than patching litellm internals.
+        A test with no assertions at all is TQ001, never TQ002.
+TQ003   `sys.path.insert(...)` inside the test tree. pytest's rootdir handling and
+        the installed package already make `litellm` importable, so these are
+        no-ops carried by copy-paste; the ones that are not no-ops make the test's
+        imports depend on the working directory it happens to run from.
+TQ004   Raw `os.environ[...] = ...` assignment. The write outlives the test and
+        leaks into whatever runs next in the same process, which is how a suite
+        acquires an ordering dependency. Use `monkeypatch.setenv`, which is undone
+        at teardown.
+TQ005   `litellm.<attr> = ...` module-global mutation. The SDK's module globals are
+        process-wide, so this is the same leak as TQ004 one level up, and it is
+        what the 491-line save/restore conftest exists to paper over. Inject the
+        dependency or use a fixture that restores it.
+
+Every rule is suppressible with `# test-quality-ok: <reason>` on the reported
+line, following the repo's `*-ok: <reason>` convention. A suppression without a
+reason does not suppress.
+
+What counts as an assertion
+---------------------------
+An `assert` statement; `pytest.raises` / `warns` / `deprecated_call` / `fail`,
+qualified or bare (`skip` and `xfail` are deliberately excluded, since they abort
+the test rather than pin a behaviour); and any callable whose name starts with
+`assert`, qualified (`m.assert_called_once`, `self.assertEqual`,
+`np.testing.assert_allclose`) or bare (`assert_auth_denied(...)`, the shape the
+e2e harness uses). A test also counts as asserting when it reaches an assertion
+through a function defined in the same module, followed transitively, because
+extracting the assertions into a shared helper is good factoring rather than a
+test that pins nothing. A helper imported from another module is not followed, so
+a test whose only assertions live across a module boundary still reports TQ001
+and needs a suppression.
+
+What counts as mock inspection (TQ002)
+--------------------------------------
+An `assert_`-prefixed call, which is mock's own family, or a reference to
+`called` / `call_args` / `call_args_list` / `call_count` / `mock_calls` and their
+await-counterparts. unittest's `assertEqual` has no underscore after "assert" and
+so is never mistaken for one. A patch is installed by any call or decorator whose
+name is `patch` or `patch.object` / `patch.dict` / `patch.multiple`, which covers
+`unittest.mock` however it was imported as well as pytest-mock's `mocker.patch`.
+
+Scope
+-----
+Only files under the test roots passed on the command line are examined, and
+TQ001/TQ002 only look at functions pytest would collect: a `test_`-prefixed
+function at module level, or a `test_`-prefixed method of a `Test`-prefixed
+class that defines no `__init__`.
+
+Usage
+-----
+    python check_test_quality.py tests/
+
+Exit code 1 if any violation is found. Stdlib only.
+"""
+
+from __future__ import annotations
+
+import ast
+import io
+import re
+import sys
+import tokenize
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from types import MappingProxyType
+from typing import Final, NamedTuple
+
+TEST_FUNCTION_PREFIX: Final = "test_"
+TEST_CLASS_PREFIX: Final = "Test"
+MIN_REASON_LEN: Final = 3
+
+SUPPRESSION_TOKEN: Final = "test-quality-ok"
+SUPPRESSION_RE: Final = re.compile(r"#\s*test-quality-ok(?::\s*(?P<reason>.*))?")
+
+PYTEST_ASSERTION_HELPERS: Final = frozenset(("raises", "warns", "deprecated_call", "fail"))
+
+MOCK_INSPECTION_ATTRIBUTES: Final = frozenset((
+    "called", "call_args", "call_args_list", "call_count", "mock_calls",
+    "await_args", "await_args_list", "await_count", "awaited",
+))
+MOCK_ASSERTION_PREFIX: Final = "assert_"
+
+PATCH_MEMBERS: Final = frozenset(("object", "dict", "multiple"))
+
+FunctionNode = ast.FunctionDef | ast.AsyncFunctionDef
+
+
+class Violation(NamedTuple):
+    path: Path
+    line: int
+    code: str
+    message: str
+
+    def render(self) -> str:
+        return f"{self.path}:{self.line}: {self.code} {self.message}"
+
+
+def _dotted_name(node: ast.expr) -> str:
+    """`a.b.c` for an attribute chain rooted in a plain name, else ""."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        root: Final = _dotted_name(node.value)
+        return f"{root}.{node.attr}" if root else ""
+    return ""
+
+
+def suppressed_lines(source: str) -> frozenset[int]:
+    """Lines carrying `# test-quality-ok: <reason>` with a reason of usable length."""
+    try:
+        tokens: Final = tuple(tokenize.generate_tokens(io.StringIO(source).readline))
+    except (tokenize.TokenError, IndentationError, SyntaxError):
+        return frozenset()
+    return frozenset(
+        token.start[0]
+        for token in tokens
+        if token.type == tokenize.COMMENT
+        and (match := SUPPRESSION_RE.search(token.string)) is not None
+        and len((match.group("reason") or "").strip()) >= MIN_REASON_LEN
+    )
+
+
+def _is_collectible_class(node: ast.ClassDef) -> bool:
+    """pytest collects `Test`-prefixed classes that define no constructor."""
+    if not node.name.startswith(TEST_CLASS_PREFIX):
+        return False
+    return not any(
+        isinstance(child, ast.FunctionDef) and child.name == "__init__"
+        for child in node.body
+    )
+
+
+def iter_test_functions(tree: ast.Module) -> Iterator[FunctionNode]:
+    """Every function pytest would collect from this module, in source order."""
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if node.name.startswith(TEST_FUNCTION_PREFIX):
+                yield node
+        elif isinstance(node, ast.ClassDef) and _is_collectible_class(node):
+            yield from (
+                child
+                for child in node.body
+                if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef))
+                and child.name.startswith(TEST_FUNCTION_PREFIX)
+            )
+
+
+def _is_pytest_assertion_call(call: ast.Call) -> bool:
+    func: Final = call.func
+    if isinstance(func, ast.Attribute):
+        return func.attr in PYTEST_ASSERTION_HELPERS
+    if isinstance(func, ast.Name):
+        return func.id in PYTEST_ASSERTION_HELPERS
+    return False
+
+
+def _is_assertion_helper_call(call: ast.Call) -> bool:
+    """Any `assert*` callable: `x.assertEqual(...)`, `m.assert_called_once()`,
+    `np.testing.assert_allclose(...)`, and the bare shared helpers the e2e harness
+    uses (`assert_auth_denied(result, ...)`)."""
+    func: Final = call.func
+    if isinstance(func, ast.Attribute):
+        return func.attr.startswith("assert")
+    return isinstance(func, ast.Name) and func.id.startswith("assert")
+
+
+def iter_assertions(function: FunctionNode) -> Iterator[ast.stmt | ast.Call]:
+    """Every node in the function that pins a behaviour, nested definitions included."""
+    for node in ast.walk(function):
+        if isinstance(node, ast.Assert):
+            yield node
+        elif isinstance(node, ast.Call) and (
+            _is_pytest_assertion_call(node) or _is_assertion_helper_call(node)
+        ):
+            yield node
+
+
+class CallTarget(NamedTuple):
+    """A call that might resolve to a function defined in this module: either a bare
+    name, looked up among the module-level functions, or a `self.` attribute, looked
+    up among the enclosing class's own methods."""
+
+    through_self: bool
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class Scope:
+    """What one function can reach by name. Keeping methods per-class is what stops
+    two same-named helpers in different classes from resolving to each other."""
+
+    module_level: Mapping[str, FunctionNode]
+    methods: Mapping[str, FunctionNode]
+
+    def resolve(self, target: CallTarget) -> FunctionNode | None:
+        source: Final = self.methods if target.through_self else self.module_level
+        return source.get(target.name)
+
+
+def _call_target(func: ast.expr) -> CallTarget | None:
+    if isinstance(func, ast.Name):
+        return CallTarget(through_self=False, name=func.id)
+    if isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name) and func.value.id == "self":
+        return CallTarget(through_self=True, name=func.attr)
+    return None
+
+
+def _call_targets(function: FunctionNode) -> frozenset[CallTarget]:
+    return frozenset(
+        target
+        for node in ast.walk(function)
+        if isinstance(node, ast.Call)
+        for target in (_call_target(node.func),)
+        if target is not None
+    )
+
+
+def _functions_in(body: Iterable[ast.stmt]) -> Mapping[str, FunctionNode]:
+    return MappingProxyType({
+        node.name: node
+        for node in body
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+    })
+
+
+def build_scopes(tree: ast.Module) -> Mapping[FunctionNode, Scope]:
+    """Every function in the module paired with what it can reach by name. A
+    module-level function sees only module-level functions; a method also sees its
+    own class's methods, and no other class's."""
+    module_level: Final = _functions_in(tree.body)
+    module_scope: Final = Scope(module_level=module_level, methods=MappingProxyType({}))
+    class_scopes: Final = tuple(
+        (node, Scope(module_level=module_level, methods=_functions_in(node.body)))
+        for node in tree.body
+        if isinstance(node, ast.ClassDef)
+    )
+    return MappingProxyType({
+        **{function: module_scope for function in module_level.values()},
+        **{
+            function: scope
+            for node, scope in class_scopes
+            for function in scope.methods.values()
+        },
+    })
+
+
+def _reaches_assertion(
+    function: FunctionNode,
+    scopes: Mapping[FunctionNode, Scope],
+    seen: frozenset[FunctionNode],
+) -> bool:
+    if function in seen:
+        return False
+    if any(iter_assertions(function)):
+        return True
+    scope: Final = scopes.get(function)
+    if scope is None:
+        return False
+    return any(
+        _reaches_assertion(callee, scopes, seen | frozenset((function,)))
+        for target in _call_targets(function)
+        for callee in (scope.resolve(target),)
+        if callee is not None
+    )
+
+
+def asserts_through_helpers(
+    function: FunctionNode, scopes: Mapping[FunctionNode, Scope]
+) -> bool:
+    """Whether the test reaches an assertion through a function defined in this
+    module, followed transitively. Extracting the assertions into a shared helper is
+    good factoring rather than a test that pins nothing, so following one is what
+    keeps TQ001 honest."""
+    scope: Final = scopes.get(function)
+    if scope is None:
+        return False
+    return any(
+        _reaches_assertion(callee, scopes, frozenset((function,)))
+        for target in _call_targets(function)
+        for callee in (scope.resolve(target),)
+        if callee is not None
+    )
+
+
+def _is_patch_installer(dotted: str) -> bool:
+    """`patch`, `mock.patch`, `mocker.patch`, `patch.object`, `mock.patch.dict`, ..."""
+    parts: Final = dotted.split(".")
+    if parts[-1] == "patch":
+        return True
+    return len(parts) >= 2 and parts[-2] == "patch" and parts[-1] in PATCH_MEMBERS
+
+
+def _installs_patch(function: FunctionNode) -> bool:
+    decorators: Final = tuple(
+        _dotted_name(d.func) if isinstance(d, ast.Call) else _dotted_name(d)
+        for d in function.decorator_list
+    )
+    if any(name and _is_patch_installer(name) for name in decorators):
+        return True
+    return any(
+        _is_patch_installer(_dotted_name(node.func))
+        for node in ast.walk(function)
+        if isinstance(node, ast.Call) and _dotted_name(node.func)
+    )
+
+
+def _only_inspects_a_mock(node: ast.stmt | ast.Call) -> bool:
+    """True when this assertion reads a mock's call record and nothing else."""
+    if isinstance(node, ast.Call):
+        func = node.func
+        return isinstance(func, ast.Attribute) and func.attr.startswith(MOCK_ASSERTION_PREFIX)
+    return any(
+        isinstance(child, ast.Attribute)
+        and (
+            child.attr in MOCK_INSPECTION_ATTRIBUTES
+            or child.attr.startswith(MOCK_ASSERTION_PREFIX)
+        )
+        for child in ast.walk(node)
+    )
+
+
+def iter_assertion_violations(path: Path, tree: ast.Module) -> Iterator[Violation]:
+    scopes: Final = build_scopes(tree)
+    for function in iter_test_functions(tree):
+        assertions: Final = tuple(iter_assertions(function))
+        if not assertions and asserts_through_helpers(function, scopes):
+            continue
+        if not assertions:
+            yield Violation(
+                path,
+                function.lineno,
+                "TQ001",
+                f"test `{function.name}` asserts nothing, so it can only fail by raising; "
+                f"assert the observable output (suppress: `# {SUPPRESSION_TOKEN}: <reason>`)",
+            )
+        elif _installs_patch(function) and all(map(_only_inspects_a_mock, assertions)):
+            yield Violation(
+                path,
+                function.lineno,
+                "TQ002",
+                f"test `{function.name}` patches something and only asserts that the mock was "
+                f"called, which restates the implementation; assert what the caller observes "
+                f"(suppress: `# {SUPPRESSION_TOKEN}: <reason>`)",
+            )
+
+
+def iter_sys_path_violations(path: Path, tree: ast.Module) -> Iterator[Violation]:
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call) and _dotted_name(node.func) == "sys.path.insert":
+            yield Violation(
+                path,
+                node.lineno,
+                "TQ003",
+                "sys.path.insert in a test; pytest's rootdir and the installed package already "
+                f"make litellm importable (suppress: `# {SUPPRESSION_TOKEN}: <reason>`)",
+            )
+
+
+def _environ_subscript_targets(target: ast.expr) -> Iterator[ast.Subscript]:
+    if isinstance(target, ast.Tuple):
+        for element in target.elts:
+            yield from _environ_subscript_targets(element)
+        return
+    if isinstance(target, ast.Subscript) and _dotted_name(target.value) in ("os.environ", "environ"):
+        yield target
+
+
+def iter_environ_violations(path: Path, tree: ast.Module) -> Iterator[Violation]:
+    for node in ast.walk(tree):
+        targets: Final = (
+            node.targets if isinstance(node, ast.Assign)
+            else (node.target,) if isinstance(node, (ast.AugAssign, ast.AnnAssign))
+            else ()
+        )
+        for target in targets:
+            for subscript in _environ_subscript_targets(target):
+                yield Violation(
+                    path,
+                    subscript.lineno,
+                    "TQ004",
+                    "raw os.environ write leaks into every test that runs after this one; "
+                    f"use monkeypatch.setenv (suppress: `# {SUPPRESSION_TOKEN}: <reason>`)",
+                )
+
+
+def _litellm_attribute_targets(target: ast.expr) -> Iterator[ast.Attribute]:
+    if isinstance(target, ast.Tuple):
+        for element in target.elts:
+            yield from _litellm_attribute_targets(element)
+        return
+    if isinstance(target, ast.Attribute) and _dotted_name(target.value) == "litellm":
+        yield target
+
+
+def iter_global_mutation_violations(path: Path, tree: ast.Module) -> Iterator[Violation]:
+    for node in ast.walk(tree):
+        targets: Final = (
+            node.targets if isinstance(node, ast.Assign)
+            else (node.target,) if isinstance(node, (ast.AugAssign, ast.AnnAssign))
+            else ()
+        )
+        for target in targets:
+            for attribute in _litellm_attribute_targets(target):
+                yield Violation(
+                    path,
+                    attribute.lineno,
+                    "TQ005",
+                    f"litellm.{attribute.attr} is a process-wide global; writing it here is what the "
+                    "save/restore conftest exists to undo, so inject the dependency or use a fixture "
+                    f"(suppress: `# {SUPPRESSION_TOKEN}: <reason>`)",
+                )
+
+
+def check_file(path: Path) -> tuple[Violation, ...]:
+    try:
+        source: Final = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return (Violation(path, 0, "TQ000", f"unreadable: {exc}"),)
+
+    try:
+        tree: Final = ast.parse(source, filename=str(path))
+    except SyntaxError as exc:
+        return (Violation(path, exc.lineno or 0, "TQ000", f"syntax error: {exc.msg}"),)
+
+    skip: Final = suppressed_lines(source)
+    return tuple(
+        violation
+        for violation in (
+            *iter_assertion_violations(path, tree),
+            *iter_sys_path_violations(path, tree),
+            *iter_environ_violations(path, tree),
+            *iter_global_mutation_violations(path, tree),
+        )
+        if violation.line not in skip
+    )
+
+
+def collect_paths(raw: Iterable[str]) -> Iterator[Path]:
+    for item in raw:
+        candidate: Final = Path(item)
+        if candidate.is_dir():
+            yield from sorted(candidate.rglob("*.py"))
+        elif candidate.suffix == ".py":
+            yield candidate
+
+
+def main(argv: Sequence[str]) -> int:
+    paths: Final = tuple(a for a in argv if not a.startswith("-"))
+    if not paths:
+        print("usage: check_test_quality.py <files-or-dirs>...", file=sys.stderr)
+        return 2
+
+    violations: Final = sorted(v for path in collect_paths(paths) for v in check_file(path))
+    for violation in violations:
+        print(violation.render())
+
+    if violations:
+        print(f"\n{len(violations)} violation(s).", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/test_quality_gate.py b/scripts/test_quality_gate.py
new file mode 100644
index 00000000000..292da29e1f2
--- /dev/null
+++ b/scripts/test_quality_gate.py
@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""Total-count gate for the TQ* rules in scripts/check_test_quality.py.
+
+Sibling of scripts/type_discipline_gate.py, pointed at the test tree instead of
+the package. Each rule listed in test-quality-budget.json has a hard ``limit``.
+The gate counts each rule across the whole `tests` tree and fails when a rule is
+both over its limit and higher than the base it merges into, so a change is
+blamed for the violations it adds, never for drift that already exists in the
+base.
+
+Every rule is seeded at exactly its count on the day the gate landed, so the
+suite's existing debt is grandfathered and any net-new violation trips the gate
+immediately. ``--update`` ratchets a limit down by the violations this branch
+fixed relative to its branch point (the merge-base), so the ceilings only ever
+fall. A rule absent from the budget at the merge-base was seeded on this branch;
+``--update`` leaves its limit untouched, because the base tree predates the rule
+and its whole grandfathered count would otherwise be misread as "fixed".
+
+The deliberate difference from its sibling: this gate has no headroom anywhere.
+Type discipline seeded LIT010/LIT011 at 1.5x to leave room for an in-flight
+sweep; a test-quality violation has no such transition to absorb, so the line is
+today's count and the only legal direction is down.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections import Counter
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from types import MappingProxyType
+from typing import Final, NamedTuple
+
+REPO_ROOT: Final = Path(__file__).resolve().parent.parent
+CHECKER: Final = REPO_ROOT / "scripts" / "check_test_quality.py"
+BUDGET_PATH: Final = REPO_ROOT / "test-quality-budget.json"
+TARGET: Final = "tests"
+DEFAULT_BASE: Final = "origin/litellm_internal_staging"
+
+_HUNK: Final = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@", re.MULTILINE)
+_FILE_HEADER: Final = re.compile(r"^\+\+\+ b/(.+)$", re.MULTILINE)
+_LINE: Final = re.compile(r"^(?P<file>.+?):(?P<line>\d+): (?P<code>TQ\d+) ")
+
+
+class Violation(NamedTuple):
+    file: str
+    line: int
+    code: str
+
+
+class Breach(NamedTuple):
+    rule: str
+    total: int
+    cap: int
+    added: int
+
+
+def _run(cmd: Sequence[str], cwd: Path = REPO_ROOT) -> str:
+    proc: Final = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)
+    if proc.returncode not in (0, 1):
+        sys.stderr.write(proc.stderr)
+        raise SystemExit(f"{cmd[0]} exited {proc.returncode}")
+    return proc.stdout
+
+
+def resolve_base_point(base_ref: str, cwd: Path = REPO_ROOT) -> str:
+    """The snapshot commit base counts are measured at: merge-base(base_ref, HEAD),
+    made aware of an in-progress merge. Mid-merge, HEAD is still the pre-merge tip,
+    so its merge-base is the old branch point and every violation the base gained
+    since then would be blamed on this change."""
+    head_point: Final = _run(["git", "merge-base", base_ref, "HEAD"], cwd=cwd).strip()
+    if not head_point:
+        return base_ref
+    merge_head: Final = _run(["git", "rev-parse", "--verify", "--quiet", "MERGE_HEAD"], cwd=cwd).strip()
+    if not merge_head:
+        return head_point
+    merge_point: Final = _run(["git", "merge-base", base_ref, merge_head], cwd=cwd).strip()
+    if not merge_point:
+        return head_point
+    older: Final = _run(["git", "merge-base", head_point, merge_point], cwd=cwd).strip()
+    return merge_point if older == head_point else head_point
+
+
+def _check(root: Path, checker: Path) -> tuple[Violation, ...]:
+    # macOS tempfile dirs (/var/...) resolve to /private/var/..., so relative_to needs both sides resolved.
+    resolved: Final = root.resolve()
+    out: Final = _run([sys.executable, str(checker), str(resolved / TARGET)], cwd=resolved)
+    return tuple(
+        Violation(
+            (resolved / match.group("file")).resolve().relative_to(resolved).as_posix(),
+            int(match.group("line")),
+            match.group("code"),
+        )
+        for line in out.splitlines()
+        if (match := _LINE.match(line)) is not None
+    )
+
+
+def head_violations() -> tuple[Violation, ...]:
+    return _check(REPO_ROOT, CHECKER)
+
+
+def count_by_rule(violations: Sequence[Violation]) -> Mapping[str, int]:
+    return MappingProxyType(dict(Counter(v.code for v in violations)))
+
+
+def base_counts(ref: str) -> Mapping[str, int]:
+    """Rule counts at `ref`, measured with the *current* rule logic rather than
+    whatever the checker looked like at that commit."""
+    parent: Final = Path(tempfile.mkdtemp(prefix="tq_base_"))
+    worktree: Final = parent / "wt"
+    try:
+        _run(["git", "worktree", "add", "--detach", str(worktree), ref])
+        (worktree / "scripts").mkdir(parents=True, exist_ok=True)
+        checker: Final = worktree / "scripts" / "check_test_quality.py"
+        shutil.copy(CHECKER, checker)
+        return count_by_rule(_check(worktree, checker))
+    finally:
+        # Teardown must never raise, or it masks the real error when the body failed.
+        subprocess.run(
+            ["git", "worktree", "remove", "--force", str(worktree)],
+            cwd=REPO_ROOT, capture_output=True, text=True,
+        )
+        shutil.rmtree(parent, ignore_errors=True)
+
+
+def over_ceiling(head: Mapping[str, int], budget: Mapping[str, Mapping[str, int]]) -> frozenset[str]:
+    """Rules whose head count already exceeds their limit. When none are, the base
+    comparison cannot change the verdict and the base worktree scan is skipped."""
+    return frozenset(
+        rule for rule, spec in budget.items() if head.get(rule, 0) > spec["limit"]
+    )
+
+
+def evaluate(
+    head: Mapping[str, int],
+    base: Mapping[str, int],
+    budget: Mapping[str, Mapping[str, int]],
+) -> tuple[Breach, ...]:
+    return tuple(sorted(
+        Breach(rule, head.get(rule, 0), spec["limit"], head.get(rule, 0) - base.get(rule, 0))
+        for rule, spec in budget.items()
+        if head.get(rule, 0) > spec["limit"] and head.get(rule, 0) > base.get(rule, 0)
+    ))
+
+
+def _hunk_lines(body: str) -> frozenset[int]:
+    return frozenset(
+        line
+        for match in _HUNK.finditer(body)
+        for start in (int(match.group(1)),)
+        for line in range(start, start + (int(match.group(2)) if match.group(2) is not None else 1))
+    )
+
+
+def parse_changed_lines(diff_text: str) -> Mapping[str, frozenset[int]]:
+    """Each file in the diff mapped to the line numbers it adds. Splitting on the
+    `+++ b/` headers keeps this a pure expression: `split` hands back
+    [preamble, path, body, path, body, ...], so each file's hunks are already
+    grouped with it."""
+    parts: Final = _FILE_HEADER.split(diff_text)
+    return MappingProxyType({
+        path: _hunk_lines(body)
+        for path, body in zip(parts[1::2], parts[2::2])
+    })
+
+
+def introduced(
+    violations: Sequence[Violation], changed: Mapping[str, frozenset[int]]
+) -> tuple[Violation, ...]:
+    return tuple(v for v in violations if v.line in changed.get(v.file, frozenset()))
+
+
+def cmd_check(base: str) -> None:
+    budget: Final = json.loads(BUDGET_PATH.read_text())
+    head: Final = head_violations()
+    head_counts: Final = count_by_rule(head)
+    if not over_ceiling(head_counts, budget):
+        print(f"OK: every TQ rule is within its test-suite ceiling (base {base})")
+        return
+    base_point: Final = resolve_base_point(base)
+    breaches: Final = evaluate(head_counts, base_counts(base_point), budget)
+    if not breaches:
+        print(f"OK: every TQ rule is within its test-suite ceiling (base {base})")
+        return
+    new: Final = introduced(
+        head,
+        parse_changed_lines(
+            _run(["git", "diff", base_point, "--unified=0", "--no-color", "--", TARGET])
+        ),
+    )
+    print(f"FAIL: TQ-rule totals exceed their limit (base {base}):")
+    for breach in breaches:
+        print(
+            f"  {breach.rule}: total {breach.total} over limit {breach.cap} "
+            f"(this change added {breach.added})"
+        )
+        for violation in sorted(v for v in new if v.code == breach.rule):
+            print(f"    {violation.file}:{violation.line}")
+    print(
+        "Fix the new violations, or give each one a reason "
+        "(`# test-quality-ok: <reason>`), or remove an equal number elsewhere; "
+        "the ceiling is the limit in test-quality-budget.json. "
+        "Run `python scripts/check_test_quality.py tests/` to see every finding."
+    )
+    raise SystemExit(1)
+
+
+def ratcheted_budget(
+    budget: Mapping[str, Mapping[str, int]],
+    current: Mapping[str, int],
+    base: Mapping[str, int],
+    seeded: frozenset[str] = frozenset(),
+) -> Mapping[str, Mapping[str, int]]:
+    """Each rule's limit lowered by the violations `current` fixed vs `base`. The drop
+    is clamped to what was actually cleared, so a limit only ever falls. Rules in
+    `seeded` were introduced on this branch and pass through untouched."""
+    return MappingProxyType({
+        rule: {
+            "limit": spec["limit"] if rule in seeded
+            else max(0, spec["limit"] - max(0, base.get(rule, 0) - current.get(rule, 0)))
+        }
+        for rule, spec in sorted(budget.items())
+    })
+
+
+def _base_budget_rules(base_point: str) -> frozenset[str]:
+    proc: Final = subprocess.run(
+        ["git", "show", f"{base_point}:{BUDGET_PATH.name}"],
+        cwd=REPO_ROOT, capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        return frozenset()
+    return frozenset(json.loads(proc.stdout))
+
+
+def cmd_update(base_ref: str = DEFAULT_BASE) -> None:
+    """Ratchet each rule's limit down by the violations this branch fixed."""
+    budget: Final = json.loads(BUDGET_PATH.read_text())
+    base_point: Final = resolve_base_point(base_ref)
+    seeded: Final = frozenset(budget) - _base_budget_rules(base_point)
+    updated: Final = ratcheted_budget(
+        budget, count_by_rule(head_violations()), base_counts(base_point), seeded
+    )
+    BUDGET_PATH.write_text(json.dumps(dict(updated), indent=2, sort_keys=True) + "\n")
+    cleared: Final = sum(budget[rule]["limit"] - updated[rule]["limit"] for rule in updated)
+    print(f"Ratcheted TQ-rule limits down by {cleared} violations this branch fixed")
+    if seeded:
+        print(
+            "Left untouched (seeded on this branch, absent from the base budget): "
+            + ", ".join(sorted(seeded))
+        )
+
+
+def cmd_seed() -> None:
+    """Write the budget from the working tree's current counts. Used once, to land
+    the gate; afterwards `--update` is the only thing that may move a limit."""
+    counts: Final = count_by_rule(head_violations())
+    BUDGET_PATH.write_text(
+        json.dumps({rule: {"limit": counts[rule]} for rule in sorted(counts)}, indent=2) + "\n"
+    )
+    print(f"Seeded {BUDGET_PATH.name} at " + ", ".join(f"{r}={counts[r]}" for r in sorted(counts)))
+
+
+def main() -> None:
+    parser: Final = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--base", default=DEFAULT_BASE)
+    parser.add_argument("--update", action="store_true")
+    parser.add_argument("--seed", action="store_true")
+    args: Final = parser.parse_args()
+    from gate_slot_lock import held_slot
+
+    with held_slot():
+        if args.seed:
+            cmd_seed()
+        elif args.update:
+            cmd_update(args.base)
+        else:
+            cmd_check(args.base)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/test-quality-budget.json b/test-quality-budget.json
new file mode 100644
index 00000000000..189e2609ce2
--- /dev/null
+++ b/test-quality-budget.json
@@ -0,0 +1,17 @@
+{
+  "TQ001": {
+    "limit": 750
+  },
+  "TQ002": {
+    "limit": 742
+  },
+  "TQ003": {
+    "limit": 1078
+  },
+  "TQ004": {
+    "limit": 770
+  },
+  "TQ005": {
+    "limit": 2835
+  }
+}
diff --git a/tests/test_litellm/test_check_test_quality.py b/tests/test_litellm/test_check_test_quality.py
new file mode 100644
index 00000000000..f9e907a4fde
--- /dev/null
+++ b/tests/test_litellm/test_check_test_quality.py
@@ -0,0 +1,307 @@
+"""Tests for scripts/check_test_quality.py.
+
+Every rule is exercised on a snippet that violates it and on one that does not, so
+dropping a rule, widening it, or inverting the suppression check makes a test fail.
+The helper-resolution cases are the regression for the false positives the rule
+produced against tests/e2e, where the assertions live in a shared helper rather than
+in the test body.
+"""
+
+import importlib.util
+import sys
+from pathlib import Path
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+_MODULE_PATH = _REPO_ROOT / "scripts" / "check_test_quality.py"
+_spec = importlib.util.spec_from_file_location("check_test_quality", _MODULE_PATH)
+checker = importlib.util.module_from_spec(_spec)
+# @dataclass(slots=True) rebuilds its class through sys.modules[__module__], so the
+# module has to be registered before exec_module runs or Scope fails to construct.
+sys.modules[_spec.name] = checker
+_spec.loader.exec_module(checker)
+
+
+def _codes(tmp_path, source):
+    snippet = tmp_path / "test_snippet.py"
+    snippet.write_text(source, encoding="utf-8")
+    return [v.code for v in checker.check_file(snippet)]
+
+
+def test_zero_assert_test_is_flagged(tmp_path):
+    assert _codes(tmp_path, "def test_nothing():\n    compute()\n") == ["TQ001"]
+
+
+def test_plain_assert_statement_clears_the_rule(tmp_path):
+    assert _codes(tmp_path, "def test_value():\n    assert compute() == 3\n") == []
+
+
+def test_pytest_raises_counts_as_an_assertion(tmp_path):
+    source = "import pytest\n\n\ndef test_raises():\n    with pytest.raises(ValueError):\n        compute()\n"
+    assert _codes(tmp_path, source) == []
+
+
+def test_unittest_style_assertion_counts(tmp_path):
+    source = "class TestThing:\n    def test_equal(self):\n        self.assertEqual(compute(), 3)\n"
+    assert _codes(tmp_path, source) == []
+
+
+def test_bare_assert_helper_call_counts(tmp_path):
+    source = "def test_denied():\n    assert_auth_denied(call(), 'missing header')\n"
+    assert _codes(tmp_path, source) == []
+
+
+def test_assertion_inside_a_module_local_helper_clears_the_rule(tmp_path):
+    source = (
+        "def _drive_and_check(client):\n"
+        "    assert client.status == 429\n"
+        "\n"
+        "\n"
+        "def test_budget_blocks(client):\n"
+        "    _drive_and_check(client)\n"
+    )
+    assert _codes(tmp_path, source) == []
+
+
+def test_helper_chain_is_followed_transitively(tmp_path):
+    source = (
+        "def _inner(x):\n"
+        "    assert x == 1\n"
+        "\n"
+        "\n"
+        "def _outer(x):\n"
+        "    _inner(x)\n"
+        "\n"
+        "\n"
+        "def test_chain():\n"
+        "    _outer(1)\n"
+    )
+    assert _codes(tmp_path, source) == []
+
+
+def test_a_same_named_helper_in_another_class_does_not_clear_the_rule(tmp_path):
+    source = (
+        "class TestAsserting:\n"
+        "    def _check(self):\n"
+        "        assert compute() == 3\n"
+        "\n"
+        "    def test_ok(self):\n"
+        "        self._check()\n"
+        "\n"
+        "\n"
+        "class TestNotAsserting:\n"
+        "    def _check(self):\n"
+        "        compute()\n"
+        "\n"
+        "    def test_nothing(self):\n"
+        "        self._check()\n"
+    )
+    assert _codes(tmp_path, source) == ["TQ001"]
+
+
+def test_self_call_resolves_to_the_enclosing_class(tmp_path):
+    source = (
+        "class TestOne:\n"
+        "    def _check(self):\n"
+        "        assert compute() == 3\n"
+        "\n"
+        "    def test_ok(self):\n"
+        "        self._check()\n"
+    )
+    assert _codes(tmp_path, source) == []
+
+
+def test_a_method_named_like_a_module_helper_does_not_shadow_it(tmp_path):
+    source = (
+        "def _check():\n"
+        "    assert compute() == 3\n"
+        "\n"
+        "\n"
+        "class TestThing:\n"
+        "    def _check(self):\n"
+        "        compute()\n"
+        "\n"
+        "    def test_bare_name_uses_the_module_helper(self):\n"
+        "        _check()\n"
+        "\n"
+        "    def test_self_uses_the_method(self):\n"
+        "        self._check()\n"
+    )
+    assert _codes(tmp_path, source) == ["TQ001"]
+
+
+def test_helper_without_assertions_does_not_clear_the_rule(tmp_path):
+    source = (
+        "def _just_calls(client):\n"
+        "    client.go()\n"
+        "\n"
+        "\n"
+        "def test_nothing_anywhere(client):\n"
+        "    _just_calls(client)\n"
+    )
+    assert _codes(tmp_path, source) == ["TQ001"]
+
+
+def test_mutually_recursive_helpers_terminate(tmp_path):
+    source = (
+        "def _a(x):\n"
+        "    _b(x)\n"
+        "\n"
+        "\n"
+        "def _b(x):\n"
+        "    _a(x)\n"
+        "\n"
+        "\n"
+        "def test_cycle():\n"
+        "    _a(1)\n"
+    )
+    assert _codes(tmp_path, source) == ["TQ001"]
+
+
+def test_non_test_function_is_not_collected(tmp_path):
+    assert _codes(tmp_path, "def helper_without_asserts():\n    compute()\n") == []
+
+
+def test_class_with_a_constructor_is_not_collected(tmp_path):
+    source = (
+        "class TestLegacy:\n"
+        "    def __init__(self):\n"
+        "        self.x = 1\n"
+        "\n"
+        "    def test_nothing(self):\n"
+        "        compute()\n"
+    )
+    assert _codes(tmp_path, source) == []
+
+
+def test_mock_echo_is_flagged(tmp_path):
+    source = (
+        "from unittest.mock import patch\n"
+        "\n"
+        "\n"
+        "def test_echo():\n"
+        "    with patch('litellm.completion') as mock_completion:\n"
+        "        run()\n"
+        "    mock_completion.assert_called_once()\n"
+    )
+    assert _codes(tmp_path, source) == ["TQ002"]
+
+
+def test_call_args_inspection_is_mock_echo(tmp_path):
+    source = (
+        "from unittest.mock import patch\n"
+        "\n"
+        "\n"
+        "def test_echo():\n"
+        "    with patch('litellm.completion') as mock_completion:\n"
+        "        run()\n"
+        "    assert mock_completion.call_args[1]['model'] == 'gpt-4o'\n"
+    )
+    assert _codes(tmp_path, source) == ["TQ002"]
+
+
+def test_patch_decorator_counts_as_installing_a_patch(tmp_path):
+    source = (
+        "from unittest import mock\n"
+        "\n"
+        "\n"
+        "@mock.patch('litellm.completion')\n"
+        "def test_echo(mock_completion):\n"
+        "    run()\n"
+        "    mock_completion.assert_called_once()\n"
+    )
+    assert _codes(tmp_path, source) == ["TQ002"]
+
+
+def test_patching_but_asserting_the_output_is_not_mock_echo(tmp_path):
+    source = (
+        "from unittest.mock import patch\n"
+        "\n"
+        "\n"
+        "def test_output():\n"
+        "    with patch('litellm.completion') as mock_completion:\n"
+        "        result = run()\n"
+        "    mock_completion.assert_called_once()\n"
+        "    assert result.choices[0].message.content == 'pong'\n"
+    )
+    assert _codes(tmp_path, source) == []
+
+
+def test_asserting_without_patching_is_not_mock_echo(tmp_path):
+    source = "def test_plain():\n    m = build()\n    assert m.called\n"
+    assert _codes(tmp_path, source) == []
+
+
+def test_a_test_with_no_assertions_is_tq001_not_tq002(tmp_path):
+    source = (
+        "from unittest.mock import patch\n"
+        "\n"
+        "\n"
+        "def test_nothing():\n"
+        "    with patch('litellm.completion'):\n"
+        "        run()\n"
+    )
+    assert _codes(tmp_path, source) == ["TQ001"]
+
+
+def test_sys_path_insert_is_flagged(tmp_path):
+    assert _codes(tmp_path, "import sys\n\nsys.path.insert(0, '..')\n") == ["TQ003"]
+
+
+def test_sys_path_read_is_not_flagged(tmp_path):
+    assert _codes(tmp_path, "import sys\n\nprint(sys.path)\n") == []
+
+
+def test_raw_environ_write_is_flagged(tmp_path):
+    assert _codes(tmp_path, "import os\n\nos.environ['KEY'] = 'v'\n") == ["TQ004"]
+
+
+def test_bare_environ_write_is_flagged(tmp_path):
+    assert _codes(tmp_path, "from os import environ\n\nenviron['KEY'] = 'v'\n") == ["TQ004"]
+
+
+def test_environ_read_is_not_flagged(tmp_path):
+    assert _codes(tmp_path, "import os\n\nvalue = os.environ.get('KEY')\n") == []
+
+
+def test_monkeypatch_setenv_is_not_flagged(tmp_path):
+    source = "def test_env(monkeypatch):\n    monkeypatch.setenv('KEY', 'v')\n    assert read() == 'v'\n"
+    assert _codes(tmp_path, source) == []
+
+
+def test_litellm_global_write_is_flagged(tmp_path):
+    assert _codes(tmp_path, "import litellm\n\nlitellm.drop_params = True\n") == ["TQ005"]
+
+
+def test_litellm_augmented_global_write_is_flagged(tmp_path):
+    assert _codes(tmp_path, "import litellm\n\nlitellm.num_retries += 1\n") == ["TQ005"]
+
+
+def test_litellm_attribute_read_is_not_flagged(tmp_path):
+    assert _codes(tmp_path, "import litellm\n\nvalue = litellm.drop_params\n") == []
+
+
+def test_unrelated_attribute_write_is_not_flagged(tmp_path):
+    assert _codes(tmp_path, "config.drop_params = True\n") == []
+
+
+def test_suppression_with_a_reason_clears_the_violation(tmp_path):
+    source = "import sys\n\nsys.path.insert(0, '..')  # test-quality-ok: vendored path is required here\n"
+    assert _codes(tmp_path, source) == []
+
+
+def test_suppression_without_a_reason_does_not_suppress(tmp_path):
+    assert _codes(tmp_path, "import sys\n\nsys.path.insert(0, '..')  # test-quality-ok:\n") == ["TQ003"]
+
+
+def test_suppression_on_another_line_does_not_suppress(tmp_path):
+    source = "import sys  # test-quality-ok: this reason sits on the wrong line\n\nsys.path.insert(0, '..')\n"
+    assert _codes(tmp_path, source) == ["TQ003"]
+
+
+def test_unparseable_source_degrades_to_tq000(tmp_path):
+    assert _codes(tmp_path, "def test_broken(:\n    pass\n") == ["TQ000"]
+
+
+def test_every_violation_renders_as_path_line_code_message():
+    rendered = checker.Violation(Path("tests/test_x.py"), 7, "TQ001", "nothing asserted").render()
+    assert rendered == "tests/test_x.py:7: TQ001 nothing asserted"
diff --git a/tests/test_litellm/test_test_quality_gate.py b/tests/test_litellm/test_test_quality_gate.py
new file mode 100644
index 00000000000..3bfaac866d7
--- /dev/null
+++ b/tests/test_litellm/test_test_quality_gate.py
@@ -0,0 +1,125 @@
+"""Tests for scripts/test_quality_gate.py.
+
+The gate's whole value is that it blames a change only for what it adds, and that a
+limit can never rise. Both properties live in pure functions, so they are tested
+directly: `evaluate` for the blame rule, `ratcheted_budget` for the one-way ratchet,
+and `parse_changed_lines` for the diff scan that turns a breach into file:line.
+"""
+
+import importlib.util
+import sys
+from pathlib import Path
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+_MODULE_PATH = _REPO_ROOT / "scripts" / "test_quality_gate.py"
+_spec = importlib.util.spec_from_file_location("test_quality_gate", _MODULE_PATH)
+gate = importlib.util.module_from_spec(_spec)
+# @dataclass(slots=True) rebuilds its class through sys.modules[__module__], so the
+# module has to be registered before exec_module runs or Scope fails to construct.
+sys.modules[_spec.name] = gate
+_spec.loader.exec_module(gate)
+
+_BUDGET = {"TQ001": {"limit": 10}, "TQ003": {"limit": 5}}
+
+
+def test_a_rule_within_its_limit_is_not_a_breach():
+    assert gate.evaluate({"TQ001": 10}, {"TQ001": 10}, _BUDGET) == ()
+
+
+def test_a_rule_over_its_limit_that_the_change_added_is_a_breach():
+    breaches = gate.evaluate({"TQ001": 12}, {"TQ001": 10}, _BUDGET)
+    assert [(b.rule, b.total, b.cap, b.added) for b in breaches] == [("TQ001", 12, 10, 2)]
+
+
+def test_drift_already_in_the_base_is_not_blamed_on_the_change():
+    assert gate.evaluate({"TQ001": 14}, {"TQ001": 14}, _BUDGET) == ()
+
+
+def test_a_change_that_reduces_an_over_limit_rule_is_not_blamed():
+    assert gate.evaluate({"TQ001": 13}, {"TQ001": 14}, _BUDGET) == ()
+
+
+def test_a_rule_absent_from_head_counts_as_zero():
+    assert gate.evaluate({}, {}, _BUDGET) == ()
+
+
+def test_over_ceiling_names_only_the_rules_above_their_limit():
+    assert gate.over_ceiling({"TQ001": 11, "TQ003": 5}, _BUDGET) == frozenset({"TQ001"})
+
+
+def test_over_ceiling_is_empty_when_everything_fits():
+    assert gate.over_ceiling({"TQ001": 10, "TQ003": 4}, _BUDGET) == frozenset()
+
+
+def test_ratchet_lowers_a_limit_by_what_the_branch_fixed():
+    updated = gate.ratcheted_budget(_BUDGET, {"TQ001": 6}, {"TQ001": 10})
+    assert updated["TQ001"]["limit"] == 6
+
+
+def test_ratchet_never_raises_a_limit_when_violations_grew():
+    updated = gate.ratcheted_budget(_BUDGET, {"TQ001": 20}, {"TQ001": 10})
+    assert updated["TQ001"]["limit"] == 10
+
+
+def test_ratchet_never_goes_below_zero():
+    updated = gate.ratcheted_budget({"TQ001": {"limit": 2}}, {"TQ001": 0}, {"TQ001": 100})
+    assert updated["TQ001"]["limit"] == 0
+
+
+def test_ratchet_leaves_a_rule_seeded_on_this_branch_untouched():
+    updated = gate.ratcheted_budget(
+        _BUDGET, {"TQ001": 0}, {"TQ001": 10}, seeded=frozenset({"TQ001"})
+    )
+    assert updated["TQ001"]["limit"] == 10
+
+
+def test_parse_changed_lines_groups_hunks_under_their_own_file():
+    diff = (
+        "diff --git a/tests/a.py b/tests/a.py\n"
+        "--- a/tests/a.py\n"
+        "+++ b/tests/a.py\n"
+        "@@ -0,0 +3,2 @@\n"
+        "+one\n"
+        "+two\n"
+        "diff --git a/tests/b.py b/tests/b.py\n"
+        "--- a/tests/b.py\n"
+        "+++ b/tests/b.py\n"
+        "@@ -0,0 +10 @@\n"
+        "+only\n"
+    )
+    changed = gate.parse_changed_lines(diff)
+    assert changed["tests/a.py"] == frozenset({3, 4})
+    assert changed["tests/b.py"] == frozenset({10})
+
+
+def test_parse_changed_lines_handles_several_hunks_in_one_file():
+    diff = (
+        "+++ b/tests/a.py\n"
+        "@@ -0,0 +1,2 @@\n"
+        "+a\n"
+        "@@ -9,0 +20,1 @@\n"
+        "+b\n"
+    )
+    assert gate.parse_changed_lines(diff)["tests/a.py"] == frozenset({1, 2, 20})
+
+
+def test_parse_changed_lines_on_an_empty_diff_is_empty():
+    assert dict(gate.parse_changed_lines("")) == {}
+
+
+def test_introduced_keeps_only_violations_on_changed_lines():
+    violations = (
+        gate.Violation("tests/a.py", 3, "TQ001"),
+        gate.Violation("tests/a.py", 99, "TQ001"),
+        gate.Violation("tests/b.py", 3, "TQ003"),
+    )
+    kept = gate.introduced(violations, {"tests/a.py": frozenset({3})})
+    assert kept == (gate.Violation("tests/a.py", 3, "TQ001"),)
+
+
+def test_the_shipped_budget_covers_every_rule_the_checker_can_emit():
+    import json
+
+    budget = json.loads((_REPO_ROOT / "test-quality-budget.json").read_text())
+    assert set(budget) == {"TQ001", "TQ002", "TQ003", "TQ004", "TQ005"}
+    assert all(spec["limit"] >= 0 for spec in budget.values())

From 76aa13cde06f7204c84645014bd7657870edb0df Mon Sep 17 00:00:00 2001
From: yuneng-jiang <yuneng@berri.ai>
Date: Thu, 20 Aug 2026 10:30:48 -0700
Subject: [PATCH 33/35] test: remove the five test functions a later definition
 shadows (#37591)

Python binds a name once per scope, so when a module or class defines the same
test twice only the last one exists. The earlier definitions are unreachable:
pytest never collects them, and nothing that references them can fail.

A sweep in August cleared nine of these. Five have appeared since, which is the
argument for a rule rather than another sweep.

Each survivor is the better version, so nothing is lost. The two SQS logger
twins additionally stub `asyncio.create_task`, which the shadowed copies did
not. The cost-calculator duplicate is a two-line stub that also takes a
`model_item` parameter no fixture supplies, so it could not have run even
unshadowed. The two `test_prompt_caching` bodies are both `pass`.

Collecting the four files reports 416 tests before and after.

`tests/proxy_unit_tests/conftest copy.py` goes with them. pytest only loads a
file named exactly `conftest.py`, nothing imports this one, and the space in the
name says what it was.
---
 .../test_bedrock_completion.py                | 17 ------
 tests/llm_translation/test_openai.py          |  6 --
 tests/local_testing/test_completion_cost.py   |  5 --
 .../logging_callback_tests/test_sqs_logger.py | 24 --------
 tests/proxy_unit_tests/conftest copy.py       | 60 -------------------
 5 files changed, 112 deletions(-)
 delete mode 100644 tests/proxy_unit_tests/conftest copy.py

diff --git a/tests/llm_translation/test_bedrock_completion.py b/tests/llm_translation/test_bedrock_completion.py
index c6d02930f8b..8dcae7cc997 100644
--- a/tests/llm_translation/test_bedrock_completion.py
+++ b/tests/llm_translation/test_bedrock_completion.py
@@ -1195,23 +1195,6 @@ def test_not_found_error():
         )
 
 
-@pytest.mark.parametrize(
-    "model",
-    [
-        "bedrock/us.anthropic.claude-3-haiku-20240307-v1:0",
-        "bedrock/us.meta.llama3-2-11b-instruct-v1:0",
-    ],
-)
-def test_bedrock_cross_region_inference(model):
-    litellm.set_verbose = True
-    response = completion(
-        model=model,
-        messages=messages,
-        max_tokens=10,
-        temperature=0.1,
-    )
-
-
 @pytest.mark.parametrize(
     "model, expected_base_model",
     [
diff --git a/tests/llm_translation/test_openai.py b/tests/llm_translation/test_openai.py
index 22acffd535f..1a14b00c7d7 100644
--- a/tests/llm_translation/test_openai.py
+++ b/tests/llm_translation/test_openai.py
@@ -285,12 +285,6 @@ class TestOpenAIChatCompletion(BaseLLMChatTest):
         """Test that tool calls with no arguments is translated correctly. Relevant issue: https://github.com/BerriAI/litellm/issues/6833"""
         pass
 
-    def test_prompt_caching(self):
-        """
-        Test that prompt caching works correctly.
-        Skip for now, as it's working locally but not in CI
-        """
-        pass
 
     def test_prompt_caching(self):
         """
diff --git a/tests/local_testing/test_completion_cost.py b/tests/local_testing/test_completion_cost.py
index cf0c645615d..551b3f064bb 100644
--- a/tests/local_testing/test_completion_cost.py
+++ b/tests/local_testing/test_completion_cost.py
@@ -2762,11 +2762,6 @@ def model_item():
     }
 
 
-@pytest.mark.parametrize("base_model_arg", ["litellm_param", "model_info"])
-def test_cost_calculator_with_base_model_with_router(base_model_arg, model_item):
-    from litellm import Router
-
-
 @pytest.mark.parametrize("base_model_arg", ["litellm_param", "model_info"])
 def test_cost_calculator_with_base_model_with_router(base_model_arg):
     from litellm import Router
diff --git a/tests/logging_callback_tests/test_sqs_logger.py b/tests/logging_callback_tests/test_sqs_logger.py
index f141ef14b25..31e9ffc5517 100644
--- a/tests/logging_callback_tests/test_sqs_logger.py
+++ b/tests/logging_callback_tests/test_sqs_logger.py
@@ -150,30 +150,6 @@ async def test_async_sqs_logger_error_flush():
 # =============================================================================
 
 
-@pytest.mark.asyncio
-async def test_async_log_success_event_adds_to_queue(monkeypatch):
-    monkeypatch.setattr("litellm.aws_sqs_callback_params", {})
-    logger = SQSLogger(sqs_queue_url="https://example.com", sqs_region_name="us-west-2")
-
-    fake_payload = {"some": "data"}
-    await logger.async_log_success_event(
-        {"standard_logging_object": fake_payload}, None, None, None
-    )
-    assert fake_payload in logger.log_queue
-
-
-@pytest.mark.asyncio
-async def test_async_log_failure_event_adds_to_queue(monkeypatch):
-    monkeypatch.setattr("litellm.aws_sqs_callback_params", {})
-    logger = SQSLogger(sqs_queue_url="https://example.com", sqs_region_name="us-west-2")
-
-    fake_payload = {"fail": True}
-    await logger.async_log_failure_event(
-        {"standard_logging_object": fake_payload}, None, None, None
-    )
-    assert fake_payload in logger.log_queue
-
-
 # =============================================================================
 # 🧾 async_send_batch Tests
 # =============================================================================
diff --git a/tests/proxy_unit_tests/conftest copy.py b/tests/proxy_unit_tests/conftest copy.py
deleted file mode 100644
index 1421700c9a8..00000000000
--- a/tests/proxy_unit_tests/conftest copy.py	
+++ /dev/null
@@ -1,60 +0,0 @@
-# conftest.py
-
-import importlib
-import os
-import sys
-
-import pytest
-
-sys.path.insert(
-    0, os.path.abspath("../..")
-)  # Adds the parent directory to the system path
-import litellm
-
-
-@pytest.fixture(scope="function", autouse=True)
-def setup_and_teardown():
-    """
-    This fixture reloads litellm before every function. To speed up testing by removing callbacks being chained.
-    """
-    curr_dir = os.getcwd()  # Get the current working directory
-    sys.path.insert(
-        0, os.path.abspath("../..")
-    )  # Adds the project directory to the system path
-
-    import litellm
-    from litellm import Router
-
-    importlib.reload(litellm)
-    try:
-        if hasattr(litellm, "proxy") and hasattr(litellm.proxy, "proxy_server"):
-            importlib.reload(litellm.proxy.proxy_server)
-    except Exception as e:
-        print(f"Error reloading litellm.proxy.proxy_server: {e}")
-
-    import asyncio
-
-    loop = asyncio.get_event_loop_policy().new_event_loop()
-    asyncio.set_event_loop(loop)
-    print(litellm)
-    # from litellm import Router, completion, aembedding, acompletion, embedding
-    yield
-
-    # Teardown code (executes after the yield point)
-    loop.close()  # Close the loop created earlier
-    asyncio.set_event_loop(None)  # Remove the reference to the loop
-
-
-def pytest_collection_modifyitems(config, items):
-    # Separate tests in 'test_amazing_proxy_custom_logger.py' and other tests
-    custom_logger_tests = [
-        item for item in items if "custom_logger" in item.parent.name
-    ]
-    other_tests = [item for item in items if "custom_logger" not in item.parent.name]
-
-    # Sort tests based on their names
-    custom_logger_tests.sort(key=lambda x: x.name)
-    other_tests.sort(key=lambda x: x.name)
-
-    # Reorder the items list
-    items[:] = custom_logger_tests + other_tests

From d7e4b1bdd011fb7efb95fb48d90a4f1cd8f1f8d7 Mon Sep 17 00:00:00 2001
From: yuneng-jiang <yuneng@berri.ai>
Date: Thu, 20 Aug 2026 10:30:55 -0700
Subject: [PATCH 34/35] feat(ci): guard shard assignment across every sharded
 test tree (#37593)

tests/proxy_unit_tests had a 30-line YAML parser inlined in its workflow that
failed the run when a test file there belonged to no shard. tests/test_litellm
is sharded the same way, with no catch-all bucket, and had no such guard: a new
directory under it (or under its proxy subtree) is collected by nothing and runs
nowhere, and the coverage census cannot see it because a token like
tests/test_litellm/test_*.py already answers 'yes, that tree runs'.

The two questions differ. The census asks whether a file runs at all, so an
ancestor path standing in for everything beneath it is a fine answer. Shard
assignment asks which shard owns a child, and there that same ancestor path is
precisely the bug. _token_covers keeps the first meaning; _token_names adds the
second, and the guard now walks a list of sharded trees rather than one hardcoded
directory. Both read the same test-path keys, so there is one workflow parser.

A directory needs a shard when it holds a test file, not when it is named test_*.
That drops the hardcoded test_configs exception and keeps fixture directories
like expected_fine_tuning_api out on their own merits.

The job keeps its name and its workflow, since assert-shard-coverage is a
required status check on litellm_internal_staging.

Verified red-first: a planted directory under tests/test_litellm, a planted
directory under tests/test_litellm/proxy, and a planted file under
tests/proxy_unit_tests each fail the guard, while a fixture-only directory does
not. 327 children across the three trees are assigned today.
---
 .github/scripts/assert_ci_coverage.py         |  85 ++++++++++++-
 .github/workflows/test-unit-proxy-db.yml      |  36 +-----
 tests/test_litellm/test_assert_ci_coverage.py | 119 ++++++++++++++++++
 3 files changed, 207 insertions(+), 33 deletions(-)
 create mode 100644 tests/test_litellm/test_assert_ci_coverage.py

diff --git a/.github/scripts/assert_ci_coverage.py b/.github/scripts/assert_ci_coverage.py
index 5b7ca9c7275..651c7d34553 100644
--- a/.github/scripts/assert_ci_coverage.py
+++ b/.github/scripts/assert_ci_coverage.py
@@ -25,6 +25,15 @@ DOCKERFILE_TOKEN_RE = re.compile(r"[A-Za-z0-9_./-]*Dockerfile[A-Za-z0-9_.-]*")
 COMMENT_RE = re.compile(r"^\s*#.*$", re.MULTILINE)
 GLOB_CHARS = frozenset("*?")
 
+# Trees whose jobs are sharded with no catch-all bucket, so every child that holds
+# tests has to be named by some shard or it runs nowhere. A child listed here is
+# itself decomposed one level deeper and is checked through its own entry.
+SHARDED_ROOTS: tuple[str, ...] = (
+    "tests/proxy_unit_tests",
+    "tests/test_litellm",
+    "tests/test_litellm/proxy",
+)
+
 
 @dataclass(frozen=True, slots=True)
 class AllowEntry:
@@ -107,20 +116,32 @@ def _built_dockerfile_tokens(scalars: Iterable[Scalar]) -> frozenset[str]:
     )
 
 
-def _glob_to_regex(token: str) -> re.Pattern[str]:
+def _glob_to_regex(token: str, *, subtree: bool) -> re.Pattern[str]:
     parts = re.split(r"(\*\*/|\*\*|\*|\?)", token)
     translated = "".join(
         {"**/": r"(?:.*/)?", "**": r".*", "*": r"[^/]*", "?": r"[^/]"}.get(part, re.escape(part)) for part in parts
     )
-    return re.compile(rf"{translated}(?:/.*)?$")
+    return re.compile(rf"{translated}(?:/.*)?$" if subtree else rf"{translated}$")
 
 
 def _token_covers(token: str, relative_path: str) -> bool:
     if GLOB_CHARS & set(token):
-        return _glob_to_regex(token).match(relative_path) is not None
+        return _glob_to_regex(token, subtree=True).match(relative_path) is not None
     return relative_path == token or relative_path.startswith(f"{token}/")
 
 
+def _token_names(token: str, relative_path: str) -> bool:
+    """Whether the token names this path itself, rather than merely containing it.
+
+    A sharded tree has no catch-all bucket, so the ancestor token the census is happy
+    with (`tests/x` standing in for everything below it) is exactly what would let a
+    newly added child ride along without a shard.
+    """
+    if GLOB_CHARS & set(token):
+        return _glob_to_regex(token, subtree=False).match(relative_path) is not None
+    return token == relative_path
+
+
 def _test_files() -> tuple[str, ...]:
     return tuple(
         sorted(
@@ -166,6 +187,45 @@ def _describe(paths: tuple[str, ...]) -> str:
     return f"{len(paths)} test file(s) invoked by no job: {names}{suffix}"
 
 
+def _holds_tests(directory: pathlib.Path) -> bool:
+    return any(directory.rglob("test_*.py"))
+
+
+def _shard_children(root: str, repo_root: pathlib.Path = REPO_ROOT) -> tuple[str, ...]:
+    """Children of a sharded root that carry tests, so each one needs its own shard.
+
+    A directory earns an entry by containing a test file rather than by being named
+    `test_*`, which is what keeps fixture directories (`test_configs`, `expected_*`)
+    out without a hand-maintained list of exceptions.
+    """
+    return tuple(
+        sorted(
+            child.relative_to(repo_root).as_posix()
+            for child in (repo_root / root).iterdir()
+            if not child.name.startswith(".")
+            and (
+                _holds_tests(child)
+                if child.is_dir()
+                else child.name.startswith("test_") and child.suffix == ".py"
+            )
+        )
+    )
+
+
+def _unassigned_shard_children(
+    tokens: frozenset[str],
+    roots: tuple[str, ...] = SHARDED_ROOTS,
+    repo_root: pathlib.Path = REPO_ROOT,
+) -> tuple[Finding, ...]:
+    return tuple(
+        Finding(subject=child, detail=f"holds tests but no shard of {root} names it")
+        for root in roots
+        if (repo_root / root).is_dir()
+        for child in _shard_children(root, repo_root)
+        if child not in roots and not any(_token_names(token, child) for token in tokens)
+    )
+
+
 def _uncovered_dockerfiles(allowlist: Allowlist, tokens: frozenset[str]) -> tuple[Finding, ...]:
     return tuple(
         Finding(subject=relative_path, detail="built by no job")
@@ -229,7 +289,26 @@ def _report(title: str, findings: tuple[Finding, ...], remedy: str) -> None:
     _write("")
 
 
+def _check_shards() -> int:
+    findings = _unassigned_shard_children(_invoked_test_tokens(_all_scalars()))
+    if findings:
+        _report(
+            "test directories and files that no shard claims",
+            findings,
+            "Add each to the shard it belongs to. A directory that is itself split across "
+            "several shards belongs in SHARDED_ROOTS instead, so its own children get checked.",
+        )
+        return 1
+
+    counted = sum(len(_shard_children(root)) for root in SHARDED_ROOTS if (REPO_ROOT / root).is_dir())
+    _write(f"OK: all {counted} test children across {len(SHARDED_ROOTS)} sharded trees are assigned to a shard.")
+    return 0
+
+
 def main() -> int:
+    if "--shards" in sys.argv[1:]:
+        return _check_shards()
+
     allowlist = _load_allowlist()
     scalars = _all_scalars()
 
diff --git a/.github/workflows/test-unit-proxy-db.yml b/.github/workflows/test-unit-proxy-db.yml
index 93fc314462e..3725e0f5805 100644
--- a/.github/workflows/test-unit-proxy-db.yml
+++ b/.github/workflows/test-unit-proxy-db.yml
@@ -42,11 +42,10 @@ concurrency:
 #     pinning the whole file to one worker (the default --dist=loadscope
 #     behavior for single-file targets).
 jobs:
-  # Fast guard — fails the workflow if a test_*.py file under
-  # tests/proxy_unit_tests/ is not referenced by any matrix entry below.
-  # The semantic-shard design (no catch-all "remaining" bucket) relies on
-  # every test file being explicitly assigned; this guard prevents a new
-  # file from silently dropping out of CI.
+  # Fast guard — fails the workflow when a test directory or file inside a sharded
+  # tree is claimed by no shard. The semantic-shard design has no catch-all bucket,
+  # so an unassigned child runs nowhere; assert_ci_coverage.py holds the tree list
+  # and reads the same test-path keys the coverage census does.
   assert-shard-coverage:
     runs-on: ubuntu-latest
     timeout-minutes: 2
@@ -56,31 +55,8 @@ jobs:
       - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           persist-credentials: false
-      - name: Assert every test_*.py is in a matrix shard
-        run: |
-          python3 - <<'PY'
-          import pathlib, sys, yaml
-          wf = yaml.safe_load(open(".github/workflows/test-unit-proxy-db.yml"))
-          matrix = wf["jobs"]["proxy-db"]["strategy"]["matrix"]["include"]
-          referenced = set()
-          for entry in matrix:
-              for token in entry["test-path"].split():
-                  if token.startswith("tests/proxy_unit_tests/"):
-                      referenced.add(pathlib.PurePosixPath(token).name)
-          actual = {p.name for p in pathlib.Path("tests/proxy_unit_tests").iterdir()
-                    if p.name.startswith("test_") and (p.suffix == ".py" or p.is_dir())
-                    and p.name != "test_configs"}
-          orphans = sorted(actual - referenced)
-          if orphans:
-              print("ERROR: the following files/dirs under tests/proxy_unit_tests/")
-              print("       are not assigned to any shard in test-unit-proxy-db.yml:")
-              for o in orphans:
-                  print(f"  - {o}")
-              print()
-              print("Add each to whichever semantic shard it belongs to.")
-              sys.exit(1)
-          print(f"OK: all {len(actual)} files assigned to a shard.")
-          PY
+      - name: Assert every test directory and file is claimed by a shard
+        run: python3 .github/scripts/assert_ci_coverage.py --shards
 
   proxy-db:
     needs: assert-shard-coverage
diff --git a/tests/test_litellm/test_assert_ci_coverage.py b/tests/test_litellm/test_assert_ci_coverage.py
new file mode 100644
index 00000000000..a7ba603e00f
--- /dev/null
+++ b/tests/test_litellm/test_assert_ci_coverage.py
@@ -0,0 +1,119 @@
+"""Tests for .github/scripts/assert_ci_coverage.py.
+
+Two guards share one workflow parser. The census asks whether a test file is run at
+all, so an ancestor path standing in for everything below it is a valid answer. The
+shard guard asks whether a sharded tree, which has no catch-all bucket, names each
+child outright, so that same ancestor path must NOT be an answer. The pair of
+matchers that splits those two questions is what these tests pin.
+"""
+
+import importlib.util
+import sys
+from pathlib import Path
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+_MODULE_PATH = _REPO_ROOT / ".github" / "scripts" / "assert_ci_coverage.py"
+_spec = importlib.util.spec_from_file_location("assert_ci_coverage", _MODULE_PATH)
+coverage = importlib.util.module_from_spec(_spec)
+sys.modules[_spec.name] = coverage  # @dataclass(slots=True) rebuilds via sys.modules
+_spec.loader.exec_module(coverage)
+
+
+def test_an_ancestor_directory_covers_a_file_but_does_not_name_it():
+    # The whole point of the split: `tests/x` answers "does it run?" but not
+    # "which shard owns it?" — accepting it for the latter is how a new child
+    # silently drops out of a tree that has no catch-all bucket.
+    assert coverage._token_covers("tests/test_litellm", "tests/test_litellm/caching") is True
+    assert coverage._token_names("tests/test_litellm", "tests/test_litellm/caching") is False
+
+
+def test_an_exact_token_both_covers_and_names():
+    assert coverage._token_covers("tests/test_litellm/caching", "tests/test_litellm/caching") is True
+    assert coverage._token_names("tests/test_litellm/caching", "tests/test_litellm/caching") is True
+
+
+def test_a_glob_names_only_what_it_matches_not_what_sits_below_it():
+    glob = "tests/test_litellm/test_*.py"
+    assert coverage._token_names(glob, "tests/test_litellm/test_router.py") is True
+    assert coverage._token_names(glob, "tests/test_litellm/test_router.py/nested.py") is False
+    assert coverage._token_names(glob, "tests/test_litellm/proxy/test_router.py") is False
+
+
+def test_a_glob_still_covers_the_subtree_for_the_census():
+    assert coverage._token_covers("tests/llm_translation/**", "tests/llm_translation/a/b.py") is True
+
+
+def test_a_directory_earns_a_shard_by_holding_tests_not_by_its_name(tmp_path):
+    fixtures = tmp_path / "expected_payloads"
+    fixtures.mkdir()
+    (fixtures / "body.json").write_text("{}")
+    tests = tmp_path / "some_area"
+    tests.mkdir()
+    (tests / "test_thing.py").write_text("def test_thing(): assert True\n")
+
+    assert coverage._holds_tests(fixtures) is False
+    assert coverage._holds_tests(tests) is True
+
+
+def test_shard_children_lists_test_dirs_and_test_files_and_skips_fixture_dirs(tmp_path):
+    root = tmp_path / "tests" / "tree"
+    (root / "billing").mkdir(parents=True)
+    (root / "billing" / "test_billing.py").write_text("def test_b(): assert True\n")
+    (root / "test_configs").mkdir()
+    (root / "test_configs" / "config.yaml").write_text("model_list: []\n")
+    (root / "test_top_level.py").write_text("def test_t(): assert True\n")
+    (root / "helpers.py").write_text("VALUE = 1\n")
+
+    assert coverage._shard_children("tests/tree", tmp_path) == (
+        "tests/tree/billing",
+        "tests/tree/test_top_level.py",
+    )
+
+
+def test_an_unnamed_child_is_reported_and_a_named_one_is_not(tmp_path):
+    root = tmp_path / "tests" / "tree"
+    (root / "claimed").mkdir(parents=True)
+    (root / "claimed" / "test_a.py").write_text("def test_a(): assert True\n")
+    (root / "orphan").mkdir()
+    (root / "orphan" / "test_b.py").write_text("def test_b(): assert True\n")
+
+    findings = coverage._unassigned_shard_children(
+        frozenset({"tests/tree/claimed"}), roots=("tests/tree",), repo_root=tmp_path
+    )
+
+    assert tuple(f.subject for f in findings) == ("tests/tree/orphan",)
+
+
+def test_the_parent_token_alone_does_not_satisfy_any_child(tmp_path):
+    root = tmp_path / "tests" / "tree"
+    (root / "billing").mkdir(parents=True)
+    (root / "billing" / "test_a.py").write_text("def test_a(): assert True\n")
+
+    findings = coverage._unassigned_shard_children(
+        frozenset({"tests/tree"}), roots=("tests/tree",), repo_root=tmp_path
+    )
+
+    assert tuple(f.subject for f in findings) == ("tests/tree/billing",)
+
+
+def test_a_child_that_is_itself_a_sharded_root_is_checked_there_not_here(tmp_path):
+    root = tmp_path / "tests" / "tree"
+    (root / "proxy" / "endpoints").mkdir(parents=True)
+    (root / "proxy" / "endpoints" / "test_a.py").write_text("def test_a(): assert True\n")
+
+    findings = coverage._unassigned_shard_children(
+        frozenset(), roots=("tests/tree", "tests/tree/proxy"), repo_root=tmp_path
+    )
+
+    assert tuple(f.subject for f in findings) == ("tests/tree/proxy/endpoints",)
+
+
+def test_every_sharded_root_named_in_the_script_exists_on_disk():
+    # A stale root would make the guard pass by checking nothing.
+    missing = [root for root in coverage.SHARDED_ROOTS if not (_REPO_ROOT / root).is_dir()]
+    assert missing == []
+
+
+def test_the_repo_as_it_stands_has_every_shard_child_assigned():
+    findings = coverage._unassigned_shard_children(coverage._invoked_test_tokens(coverage._all_scalars()))
+    assert [f.subject for f in findings] == []

From d2d158f27180bcc80b9ffd458f18c07511fcb432 Mon Sep 17 00:00:00 2001
From: tin-berri <tin@berri.ai>
Date: Thu, 20 Aug 2026 10:43:27 -0700
Subject: [PATCH 35/35] feat(ui): multi-key shadow eval picker and per-key
 breakdown (#37389)

Stacked on the multi-key shadow eval backend. The key picker becomes a
paginated multi-select with chips, built on the base-ui combobox chips
primitives, with the pagination and debounced-search logic extracted into a
shared usePaginatedCombobox hook that PaginatedSearchSelect now also uses.
The detail view gains a per key table showing each key's own status, judged
turns against its budget, and win rates from the by_key slice, and the job
headline pluralises to "N keys" for multi-key jobs
---
 .../_components/ShadowEvalSection.test.tsx    | 131 +++++++++-
 .../_components/ShadowEvalSection.tsx         | 133 +++++++---
 .../shared/PaginatedMultiSelect.test.tsx      | 238 ++++++++++++++++++
 .../shared/PaginatedMultiSelect.tsx           | 147 +++++++++++
 .../shared/PaginatedSearchSelect.tsx          |  26 +-
 .../components/shared/usePaginatedCombobox.ts |  42 ++++
 6 files changed, 657 insertions(+), 60 deletions(-)
 create mode 100644 ui/litellm-dashboard/src/components/shared/PaginatedMultiSelect.test.tsx
 create mode 100644 ui/litellm-dashboard/src/components/shared/PaginatedMultiSelect.tsx
 create mode 100644 ui/litellm-dashboard/src/components/shared/usePaginatedCombobox.ts

diff --git a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/ShadowEvalSection.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/ShadowEvalSection.test.tsx
index b307e3d0f2a..b72ebdc9c07 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/ShadowEvalSection.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/ShadowEvalSection.test.tsx
@@ -1,4 +1,4 @@
-import { fireEvent, render, screen } from "@testing-library/react";
+import { fireEvent, render, screen, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import React from "react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
@@ -135,6 +135,7 @@ const keyEntry = (
   api_key_id,
   max_turns: 200,
   stopped_at: null,
+  attempt_count: null,
   key_alias: null,
   key_name: null,
   ...overrides,
@@ -359,15 +360,19 @@ describe("ShadowEvalSection", () => {
     expect(container).toBeEmptyDOMElement();
   });
 
-  it("keeps the start button disabled until key, router, and judge model are picked, then submits the key as a list", async () => {
+  it("keeps the start button disabled until key, router, and judge model are picked, then submits every picked key", async () => {
     const user = userEvent.setup();
     const { start } = mockHooks({});
     render(<ShadowEvalSection />);
 
     expect(screen.getByText("Start shadow eval")).toBeDisabled();
 
-    await user.click(screen.getByPlaceholderText("Search keys by alias"));
-    await user.click(await screen.findByText("prod-alpha"));
+    const keyInput = screen.getByPlaceholderText("Search keys by alias");
+    await user.click(keyInput);
+    const keyList = await screen.findByTestId("paginated-multi-select-list");
+    await user.click(within(keyList).getByText("prod-alpha"));
+    await user.click(keyInput);
+    await user.click(within(keyList).getByText("staging-beta"));
     await user.click(screen.getByPlaceholderText("Select an auto-router"));
     await user.click(await screen.findByText("gpt-auto"));
 
@@ -378,7 +383,7 @@ describe("ShadowEvalSection", () => {
     await user.click(screen.getByText("Start shadow eval"));
 
     const expectedBody = {
-      api_key_ids: ["hash-alpha"],
+      api_key_ids: ["hash-alpha", "hash-beta"],
       router_name: "gpt-auto",
       direction: "forward",
       shadow_percentage: 10,
@@ -399,7 +404,8 @@ describe("ShadowEvalSection", () => {
     await user.click(screen.getByText("Adoption check: key's traffic vs the router"));
     await user.click(await screen.findByText("Regression check: router's picks vs a baseline"));
     await user.click(screen.getByPlaceholderText("Search keys by alias"));
-    await user.click(await screen.findByText("prod-alpha"));
+    const keyList = await screen.findByTestId("paginated-multi-select-list");
+    await user.click(within(keyList).getByText("prod-alpha"));
     await user.click(screen.getByPlaceholderText("Select an auto-router"));
     await user.click(await screen.findByText("gpt-auto"));
     await user.click(screen.getByPlaceholderText("Select a judge model"));
@@ -451,6 +457,119 @@ describe("ShadowEvalSection", () => {
     expect(shadowedKeyLabel(keyEntry("hashed-key-abc"))).toBe("hashed-key…");
   });
 
+  it("breaks results down per key, so one key exhausting its own budget is visible while a sibling runs on", () => {
+    mockHooks({
+      jobs: [
+        job({
+          judged_count: 205,
+          keys: [
+            keyEntry("hash-spent", { max_turns: 200, stopped_at: "2026-08-08T00:00:00Z" }),
+            keyEntry("hash-hungry", { max_turns: 500 }),
+          ],
+          results: {
+            by_tier: [],
+            by_current_model: [],
+            by_key: [
+              {
+                group: "hash-spent",
+                turn_count: 200,
+                real_win_rate_pct: 20.0,
+                shadow_win_rate_pct: 60.0,
+                tie_rate_pct: 20.0,
+                avg_judge_confidence: 0.9,
+              },
+            ],
+            overall_shadow_win_rate_pct: 60.0,
+            overall_tie_rate_pct: 20.0,
+          },
+        }),
+      ],
+    });
+    render(<ShadowEvalSection />);
+
+    const spent = screen.getByText("hash-spent…").closest("tr");
+    const hungry = screen.getByText("hash-hungr…").closest("tr");
+    if (!spent || !hungry) throw new Error("expected a table row per scoped key");
+
+    expect(within(spent).getByText("stopped")).toBeInTheDocument();
+    expect(within(spent).getByText("200 / 200")).toBeInTheDocument();
+    expect(within(spent).getByText("60.0%")).toBeInTheDocument();
+
+    expect(within(hungry).getByText("running")).toBeInTheDocument();
+    expect(within(hungry).getByText("0 / 500")).toBeInTheDocument();
+    expect(within(hungry).getByText("No verdicts yet")).toBeInTheDocument();
+
+    expect(screen.getByText(/205 of 700 turns judged/)).toBeInTheDocument();
+    expect(screen.getByText(/Shadowing 10% of/)).toBeInTheDocument();
+    expect(screen.getByText("2 keys")).toBeInTheDocument();
+  });
+
+  it("reads a key that spent its budget as completed even before the sweep stamps it", () => {
+    mockHooks({
+      jobs: [
+        job({
+          keys: [
+            keyEntry("hash-spent", { max_turns: 200, attempt_count: 200 }),
+            keyEntry("hash-hungry", { max_turns: 500, attempt_count: 3 }),
+          ],
+        }),
+      ],
+    });
+    render(<ShadowEvalSection />);
+
+    const spent = screen.getByText("hash-spent…").closest("tr");
+    const hungry = screen.getByText("hash-hungr…").closest("tr");
+    if (!spent || !hungry) throw new Error("expected a table row per scoped key");
+    expect(within(spent).getByText("completed")).toBeInTheDocument();
+    expect(within(spent).getByText("200 / 200")).toBeInTheDocument();
+    expect(within(hungry).getByText("running")).toBeInTheDocument();
+    expect(within(hungry).getByText("3 / 500")).toBeInTheDocument();
+  });
+
+  it("shows the per-key table while a multi-key job is still collecting, before any verdicts exist", () => {
+    mockHooks({
+      jobs: [
+        job({
+          judged_count: 0,
+          results: null,
+          keys: [
+            keyEntry("hash-spent", { max_turns: 2, attempt_count: 2 }),
+            keyEntry("hash-hungry", { max_turns: 500, attempt_count: 1 }),
+          ],
+        }),
+      ],
+    });
+    render(<ShadowEvalSection />);
+
+    const spent = screen.getByText("hash-spent…").closest("tr");
+    if (!spent) throw new Error("expected a per-key row before verdicts exist");
+    expect(within(spent).getByText("completed")).toBeInTheDocument();
+    expect(within(spent).getByText("2 / 2")).toBeInTheDocument();
+    expect(screen.getByText("Budget used")).toBeInTheDocument();
+    expect(screen.queryByText("Judged turns")).not.toBeInTheDocument();
+    expect(screen.getByText(/Collecting verdicts/)).toBeInTheDocument();
+  });
+
+  it("reads every key as completed once the job's window closes, whatever its own stop state", () => {
+    mockHooks({
+      jobs: [
+        job({
+          status: "completed",
+          keys: [
+            keyEntry("hash-spent", { max_turns: 200, stopped_at: "2026-08-08T00:00:00Z" }),
+            keyEntry("hash-hungry", { max_turns: 500 }),
+          ],
+        }),
+      ],
+    });
+    render(<ShadowEvalSection />);
+
+    const hungry = screen.getByText("hash-hungr…").closest("tr");
+    if (!hungry) throw new Error("expected a table row per scoped key");
+    expect(within(hungry).getByText("completed")).toBeInTheDocument();
+    expect(within(hungry).queryByText("running")).not.toBeInTheDocument();
+  });
+
   it("keeps an older job's verdicts reachable through the previous evaluations list", async () => {
     const user = userEvent.setup();
     const emptyOverrides: Partial<ShadowEvalJob> = {
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/ShadowEvalSection.tsx b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/ShadowEvalSection.tsx
index b7b512cba0d..bc5044feaa6 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/ShadowEvalSection.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/ShadowEvalSection.tsx
@@ -6,7 +6,7 @@ import { useInfiniteKeys } from "@/app/(dashboard)/hooks/keys/useKeys";
 import useAuthorized from "@/app/(dashboard)/hooks/useAuthorized";
 import { useModelCostMap } from "@/app/(dashboard)/hooks/models/useModelCostMap";
 import { useAutoRouters, usePlainModelGroups } from "@/app/(dashboard)/hooks/models/useModels";
-import { PaginatedSearchSelect } from "@/components/shared/PaginatedSearchSelect";
+import { PaginatedMultiSelect } from "@/components/shared/PaginatedMultiSelect";
 import { SearchSelect, type SearchSelectOption } from "@/components/shared/SearchSelect";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -59,6 +59,13 @@ const shadowedKeysLabel = (job: ShadowEvalJob): string =>
 
 const totalBudget = (job: ShadowEvalJob): number => job.keys.reduce((sum, key) => sum + key.max_turns, 0);
 
+const keySpent = (key: ShadowEvalJobKey): boolean => key.attempt_count != null && key.attempt_count >= key.max_turns;
+
+const keyStatus = (job: ShadowEvalJob, key: ShadowEvalJobKey): string => {
+  if (job.status === "completed" || (key.stopped_at == null && keySpent(key))) return "completed";
+  return key.stopped_at != null ? "stopped" : "running";
+};
+
 const jobHeadline = (job: ShadowEvalJob): React.ReactNode =>
   job.direction === "reverse" ? (
     <>
@@ -175,6 +182,55 @@ const VerdictBar: React.FC<{ direction: ShadowEvalDirection; results: NonNullabl
   );
 };
 
+const KeyTable: React.FC<{ job: ShadowEvalJob }> = ({ job }) => {
+  const slices = new Map((job.results?.by_key ?? []).map((slice) => [slice.group, slice]));
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>Key</TableHead>
+          <TableHead>Status</TableHead>
+          {["Budget used", "Router wins", `${otherArmLabel(job.direction)} wins`].map((label) => (
+            <TableHead key={label} className="text-right">
+              {label}
+            </TableHead>
+          ))}
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {job.keys.map((key) => {
+          const slice = slices.get(key.api_key_id);
+          return (
+            <TableRow key={key.api_key_id}>
+              <TableCell className="font-medium text-foreground">{shadowedKeyLabel(key)}</TableCell>
+              <TableCell>
+                <StatusBadge status={keyStatus(job, key)} />
+              </TableCell>
+              <TableCell className="text-right tabular-nums">
+                {(key.attempt_count ?? slice?.turn_count ?? 0).toLocaleString()} / {key.max_turns.toLocaleString()}
+              </TableCell>
+              {slice ? (
+                <>
+                  <TableCell className="text-right font-medium tabular-nums text-foreground">
+                    {pct(routerWinRate(job.direction, slice))}
+                  </TableCell>
+                  <TableCell className="text-right tabular-nums">
+                    {pct(otherArmWinRate(job.direction, slice))}
+                  </TableCell>
+                </>
+              ) : (
+                <TableCell colSpan={2} className="text-right text-muted-foreground">
+                  No verdicts yet
+                </TableCell>
+              )}
+            </TableRow>
+          );
+        })}
+      </TableBody>
+    </Table>
+  );
+};
+
 const emptyResultsText = (job: ShadowEvalJob, resultsError: boolean): string => {
   if (resultsError) return "Results could not be loaded. Retrying.";
   if (isActive(job)) return "Collecting verdicts. Results appear as sampled requests are judged.";
@@ -184,32 +240,45 @@ const emptyResultsText = (job: ShadowEvalJob, resultsError: boolean): string =>
 
 const ResultsBody: React.FC<{ job: ShadowEvalJob; resultsError?: boolean }> = ({ job, resultsError = false }) => {
   const results = job.results;
-  const stratifications = results ? [results.by_tier, results.by_current_model, results.by_key] : [];
-  if (!results || stratifications.every((slices) => slices.length === 0)) {
-    return <p className="px-6 py-8 text-center text-sm text-muted-foreground">{emptyResultsText(job, resultsError)}</p>;
-  }
+  const hasVerdicts = results != null && (results.by_tier.length > 0 || results.by_current_model.length > 0);
   return (
     <>
-      <div className="flex flex-col gap-1 border-b px-6 py-4">
-        <p className="text-[11px] uppercase tracking-wide text-muted-foreground">
-          Router matched or beat {job.direction === "reverse" ? "the baseline" : "your current model"}
-        </p>
-        <p className="text-3xl font-semibold text-foreground">{pct(routerMatchedOrBeatPct(job.direction, results))}</p>
-        <p className="text-xs text-muted-foreground">of {(job.judged_count ?? 0).toLocaleString()} judged responses</p>
-      </div>
-      <VerdictBar direction={job.direction} results={results} />
-      {results.by_current_model.length > 0 && (
-        <SliceTable
-          groupHeader={job.direction === "reverse" ? "Router pick" : "Compared against"}
-          direction={job.direction}
-          slices={results.by_current_model}
-        />
-      )}
-      {results.by_tier.length > 0 && (
-        <div className={results.by_current_model.length > 0 ? "border-t" : ""}>
-          <SliceTable groupHeader="Prompt difficulty" direction={job.direction} slices={results.by_tier} />
+      {job.keys.length > 1 && (
+        <div className="border-b">
+          <KeyTable job={job} />
         </div>
       )}
+      {/* results == null re-stated for TS narrowing; hasVerdicts alone cannot narrow it */}
+      {!hasVerdicts || results == null ? (
+        <p className="px-6 py-8 text-center text-sm text-muted-foreground">{emptyResultsText(job, resultsError)}</p>
+      ) : (
+        <>
+          <div className="flex flex-col gap-1 border-b px-6 py-4">
+            <p className="text-[11px] uppercase tracking-wide text-muted-foreground">
+              Router matched or beat {job.direction === "reverse" ? "the baseline" : "your current model"}
+            </p>
+            <p className="text-3xl font-semibold text-foreground">
+              {pct(routerMatchedOrBeatPct(job.direction, results))}
+            </p>
+            <p className="text-xs text-muted-foreground">
+              of {(job.judged_count ?? 0).toLocaleString()} judged responses
+            </p>
+          </div>
+          <VerdictBar direction={job.direction} results={results} />
+          {results.by_current_model.length > 0 && (
+            <SliceTable
+              groupHeader={job.direction === "reverse" ? "Router pick" : "Compared against"}
+              direction={job.direction}
+              slices={results.by_current_model}
+            />
+          )}
+          {results.by_tier.length > 0 && (
+            <div className={results.by_current_model.length > 0 ? "border-t" : ""}>
+              <SliceTable groupHeader="Prompt difficulty" direction={job.direction} slices={results.by_tier} />
+            </div>
+          )}
+        </>
+      )}
     </>
   );
 };
@@ -306,9 +375,9 @@ const DIRECTION_OPTIONS: readonly { value: ShadowEvalDirection; label: string }[
 
 const START_FORM_DESCRIPTION: Record<ShadowEvalDirection, string> = {
   forward:
-    "Duplicates a sampled slice of the key's traffic through the auto-router and has an LLM judge compare both answers blind. The router's answers are never served to users; judge calls bill to the shadowed key.",
+    "Duplicates a sampled slice of the selected keys' traffic through the auto-router and has an LLM judge compare both answers blind. Each key gets its own turn budget. The router's answers are never served to users; judge calls bill to the shadowed key.",
   reverse:
-    "Duplicates a sampled slice of the traffic the auto-router already serves against a fixed baseline model and has an LLM judge compare both answers blind. The baseline's answers are never served to users; judge calls bill to the shadowed key.",
+    "Duplicates a sampled slice of the traffic the auto-router already serves against a fixed baseline model and has an LLM judge compare both answers blind. Each key gets its own turn budget. The baseline's answers are never served to users; judge calls bill to the shadowed key.",
 };
 
 const DURATION_OPTIONS = [
@@ -333,7 +402,7 @@ const Field: React.FC<{ label: string; htmlFor?: string; className?: string; chi
   </div>
 );
 
-const KeySelect: React.FC<{ value: string; onChange: (token: string) => void }> = ({ value, onChange }) => {
+const KeySelect: React.FC<{ value: string[]; onChange: (tokens: string[]) => void }> = ({ value, onChange }) => {
   const [search, setSearch] = useState("");
   const { data, isPending, isError, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteKeys(50, {
     selectedKeyAlias: search || null,
@@ -350,7 +419,7 @@ const KeySelect: React.FC<{ value: string; onChange: (token: string) => void }>
     [data],
   );
   return (
-    <PaginatedSearchSelect
+    <PaginatedMultiSelect
       inputId="shadow-eval-key"
       options={options}
       value={value}
@@ -369,7 +438,7 @@ const KeySelect: React.FC<{ value: string; onChange: (token: string) => void }>
 
 const StartForm: React.FC = () => {
   const { accessToken } = useAuthorized();
-  const [apiKeyId, setApiKeyId] = useState("");
+  const [apiKeyIds, setApiKeyIds] = useState<string[]>([]);
   const [routerName, setRouterName] = useState("");
   const [direction, setDirection] = useState<ShadowEvalDirection>("forward");
   const [baselineModel, setBaselineModel] = useState("");
@@ -394,12 +463,12 @@ const StartForm: React.FC = () => {
   const parsedMaxTurns = Number.parseInt(maxTurns, 10);
   const maxTurnsValid = parsedMaxTurns >= 1 && parsedMaxTurns <= 2000;
   const baselinePicked = direction === "forward" || baselineModel !== "";
-  const filled = [apiKeyId, routerName, judgeModel].every((field) => field !== "") && baselinePicked;
+  const filled = apiKeyIds.length > 0 && [routerName, judgeModel].every((field) => field !== "") && baselinePicked;
   const boundsValid = percentageValid && maxTurnsValid;
   const valid = Boolean(accessToken) && filled && boundsValid;
   const handleStart = () => {
     const startBody = {
-      api_key_ids: [apiKeyId],
+      api_key_ids: apiKeyIds,
       router_name: routerName,
       direction,
       ...(direction === "reverse" ? { baseline_model: baselineModel } : {}),
@@ -436,8 +505,8 @@ const StartForm: React.FC = () => {
               </SelectContent>
             </Select>
           </Field>
-          <Field label="Key to shadow" htmlFor="shadow-eval-key">
-            <KeySelect value={apiKeyId} onChange={setApiKeyId} />
+          <Field label="Keys to shadow" htmlFor="shadow-eval-key">
+            <KeySelect value={apiKeyIds} onChange={setApiKeyIds} />
           </Field>
           <Field label="Auto-router">
             <SearchSelect
diff --git a/ui/litellm-dashboard/src/components/shared/PaginatedMultiSelect.test.tsx b/ui/litellm-dashboard/src/components/shared/PaginatedMultiSelect.test.tsx
new file mode 100644
index 00000000000..140a55b1e62
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/shared/PaginatedMultiSelect.test.tsx
@@ -0,0 +1,238 @@
+import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useState } from "react";
+import { describe, expect, it, vi } from "vitest";
+
+import { PaginatedMultiSelect } from "./PaginatedMultiSelect";
+import type { SearchSelectOption } from "./SearchSelect";
+
+const OPTIONS: SearchSelectOption[] = [
+  { label: "alias-alpha", value: "alias-alpha" },
+  { label: "alias-beta", value: "alias-beta" },
+  { label: "gamma-key", value: "gamma-key" },
+];
+
+function renderSelect(overrides: Partial<React.ComponentProps<typeof PaginatedMultiSelect>> = {}) {
+  const props: React.ComponentProps<typeof PaginatedMultiSelect> = {
+    options: OPTIONS,
+    onValueChange: vi.fn(),
+    onSearchChange: vi.fn(),
+    onLoadMore: vi.fn(),
+    ...overrides,
+  };
+  render(<PaginatedMultiSelect {...props} />);
+  return props;
+}
+
+function setListMetrics(list: HTMLElement, metrics: { scrollTop: number; clientHeight: number; scrollHeight: number }) {
+  Object.defineProperty(list, "scrollTop", { value: metrics.scrollTop, configurable: true });
+  Object.defineProperty(list, "clientHeight", { value: metrics.clientHeight, configurable: true });
+  Object.defineProperty(list, "scrollHeight", { value: metrics.scrollHeight, configurable: true });
+}
+
+function chipRemoveButton(label: string): HTMLElement {
+  const chip = screen.getByText(label).closest('[data-slot="combobox-chip"]');
+  if (chip === null) throw new Error(`no chip found for ${label}`);
+  const button = chip.querySelector('[data-slot="combobox-chip-remove"]');
+  if (button === null) throw new Error(`no remove control found on chip for ${label}`);
+  return button as HTMLElement;
+}
+
+describe("PaginatedMultiSelect", () => {
+  it("reports the cleared query upstream after a selection, so the next open is not still filtered", async () => {
+    const user = userEvent.setup();
+    const onSearchChange = vi.fn();
+
+    function Controlled() {
+      const [value, setValue] = useState<string[]>([]);
+      return (
+        <PaginatedMultiSelect
+          options={OPTIONS}
+          value={value}
+          onValueChange={setValue}
+          onSearchChange={onSearchChange}
+          onLoadMore={vi.fn()}
+        />
+      );
+    }
+    render(<Controlled />);
+
+    const input = screen.getByRole("combobox");
+    await user.click(input);
+    await user.type(input, "alias-a");
+    await waitFor(() => expect(onSearchChange).toHaveBeenCalledWith("alias-a"), { timeout: 2000 });
+
+    const list = await screen.findByTestId("paginated-multi-select-list");
+    await user.click(within(list).getByText("alias-alpha"));
+
+    expect(input).toHaveValue("");
+    await waitFor(() => expect(onSearchChange).toHaveBeenLastCalledWith(""), { timeout: 2000 });
+  });
+
+  it("selects multiple values and reports them cumulatively", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+
+    function Controlled() {
+      const [value, setValue] = useState<string[]>([]);
+      return (
+        <PaginatedMultiSelect
+          options={OPTIONS}
+          value={value}
+          onValueChange={(next) => {
+            setValue(next);
+            onValueChange(next);
+          }}
+          onSearchChange={vi.fn()}
+          onLoadMore={vi.fn()}
+        />
+      );
+    }
+    render(<Controlled />);
+
+    const input = screen.getByRole("combobox");
+    await user.click(input);
+    const list = await screen.findByTestId("paginated-multi-select-list");
+    await user.click(within(list).getByText("alias-alpha"));
+
+    await user.click(input);
+    await user.click(within(list).getByText("gamma-key"));
+
+    expect(onValueChange).toHaveBeenLastCalledWith(["alias-alpha", "gamma-key"]);
+    const chips = document.querySelector('[data-slot="combobox-chips"]') as HTMLElement;
+    expect(within(chips).getByText("alias-alpha")).toBeInTheDocument();
+    expect(within(chips).getByText("gamma-key")).toBeInTheDocument();
+  });
+
+  it("deselects one value via the chip remove control and keeps the rest", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+
+    function Controlled() {
+      const [value, setValue] = useState<string[]>(["alias-alpha", "alias-beta"]);
+      return (
+        <PaginatedMultiSelect
+          options={OPTIONS}
+          value={value}
+          onValueChange={(next) => {
+            setValue(next);
+            onValueChange(next);
+          }}
+          onSearchChange={vi.fn()}
+          onLoadMore={vi.fn()}
+        />
+      );
+    }
+    render(<Controlled />);
+
+    await user.click(chipRemoveButton("alias-alpha"));
+
+    expect(onValueChange).toHaveBeenCalledWith(["alias-beta"]);
+    expect(screen.queryByText("alias-alpha")).not.toBeInTheDocument();
+    expect(screen.getByText("alias-beta")).toBeInTheDocument();
+  });
+
+  it("keeps a selected chip visible after the options page no longer contains it", () => {
+    const { rerender } = render(
+      <PaginatedMultiSelect
+        options={OPTIONS}
+        value={["ghost-key"]}
+        onValueChange={vi.fn()}
+        onSearchChange={vi.fn()}
+        onLoadMore={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByText("ghost-key")).toBeInTheDocument();
+
+    rerender(
+      <PaginatedMultiSelect
+        options={[{ label: "alias-beta", value: "alias-beta" }]}
+        value={["ghost-key"]}
+        onValueChange={vi.fn()}
+        onSearchChange={vi.fn()}
+        onLoadMore={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByText("ghost-key")).toBeInTheDocument();
+  });
+
+  it("keeps a picked chip's label after the search filters it off the options page", async () => {
+    const user = userEvent.setup();
+
+    const aliased: SearchSelectOption[] = [
+      { label: "Prod Alpha", value: "hash-alpha" },
+      { label: "Staging Beta", value: "hash-beta" },
+    ];
+
+    function Controlled({ options }: { options: SearchSelectOption[] }) {
+      const [value, setValue] = useState<string[]>([]);
+      return (
+        <PaginatedMultiSelect
+          options={options}
+          value={value}
+          onValueChange={setValue}
+          onSearchChange={vi.fn()}
+          onLoadMore={vi.fn()}
+        />
+      );
+    }
+    const { rerender } = render(<Controlled options={aliased} />);
+
+    const input = screen.getByRole("combobox");
+    await user.click(input);
+    const list = await screen.findByTestId("paginated-multi-select-list");
+    await user.click(within(list).getByText("Prod Alpha"));
+
+    rerender(<Controlled options={[{ label: "Staging Beta", value: "hash-beta" }]} />);
+
+    const chips = document.querySelector('[data-slot="combobox-chips"]') as HTMLElement;
+    expect(within(chips).getByText("Prod Alpha")).toBeInTheDocument();
+    expect(within(chips).queryByText("hash-alpha")).not.toBeInTheDocument();
+  });
+
+  it("anchors the dropdown to the chips container so it tracks the growing chip box", async () => {
+    const user = userEvent.setup();
+    renderSelect({});
+
+    await user.click(screen.getByRole("combobox"));
+    await screen.findByTestId("paginated-multi-select-list");
+
+    const content = document.querySelector('[data-slot="combobox-content"]');
+    expect(content).toHaveAttribute("data-chips", "true");
+  });
+
+  it("does not request the next page on scroll when there is no next page", async () => {
+    const user = userEvent.setup();
+    const onLoadMore = vi.fn();
+    renderSelect({ onLoadMore, hasNextPage: false });
+
+    const input = screen.getByRole("combobox");
+    await user.click(input);
+    const list = await screen.findByTestId("paginated-multi-select-list");
+
+    setListMetrics(list, { scrollTop: 900, clientHeight: 100, scrollHeight: 1000 });
+    fireEvent.scroll(list);
+
+    expect(onLoadMore).not.toHaveBeenCalled();
+  });
+
+  it("requests the next page once scrolled past the threshold when a next page exists", async () => {
+    const user = userEvent.setup();
+    const onLoadMore = vi.fn();
+    renderSelect({ onLoadMore, hasNextPage: true });
+
+    const input = screen.getByRole("combobox");
+    await user.click(input);
+    const list = await screen.findByTestId("paginated-multi-select-list");
+
+    setListMetrics(list, { scrollTop: 0, clientHeight: 100, scrollHeight: 1000 });
+    fireEvent.scroll(list);
+    expect(onLoadMore).not.toHaveBeenCalled();
+
+    setListMetrics(list, { scrollTop: 850, clientHeight: 100, scrollHeight: 1000 });
+    fireEvent.scroll(list);
+    expect(onLoadMore).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/ui/litellm-dashboard/src/components/shared/PaginatedMultiSelect.tsx b/ui/litellm-dashboard/src/components/shared/PaginatedMultiSelect.tsx
new file mode 100644
index 00000000000..233c527d1a7
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/shared/PaginatedMultiSelect.tsx
@@ -0,0 +1,147 @@
+"use client";
+
+import { Loader2 } from "lucide-react";
+import { useMemo, useState } from "react";
+
+import {
+  Combobox,
+  ComboboxChip,
+  ComboboxChips,
+  ComboboxChipsInput,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxValue,
+  useComboboxAnchor,
+} from "@/components/ui/combobox";
+
+import type { SearchSelectOption } from "./SearchSelect";
+import { usePaginatedCombobox } from "./usePaginatedCombobox";
+
+interface PaginatedMultiSelectProps {
+  options: SearchSelectOption[];
+  value?: string[];
+  onValueChange: (value: string[]) => void;
+  onSearchChange: (query: string) => void;
+  onLoadMore: () => void;
+  hasNextPage?: boolean;
+  isLoading?: boolean;
+  isFetchingNextPage?: boolean;
+  placeholder?: string;
+  emptyText?: string;
+  errorText?: string;
+  loadingText?: string;
+  disabled?: boolean;
+  className?: string;
+  inputId?: string;
+  "aria-invalid"?: true | undefined;
+  "aria-describedby"?: string;
+}
+
+export function PaginatedMultiSelect({
+  options,
+  value = [],
+  onValueChange,
+  onSearchChange,
+  onLoadMore,
+  hasNextPage = false,
+  isLoading = false,
+  isFetchingNextPage = false,
+  placeholder = "Search…",
+  emptyText = "No results",
+  errorText,
+  loadingText = "Loading…",
+  disabled = false,
+  className,
+  inputId,
+  "aria-invalid": ariaInvalid,
+  "aria-describedby": ariaDescribedBy,
+}: PaginatedMultiSelectProps) {
+  const anchor = useComboboxAnchor();
+  const [query, setQuery] = useState("");
+  const [pickedOptions, setPickedOptions] = useState<ReadonlyMap<string, SearchSelectOption>>(new Map());
+
+  const selected = useMemo<SearchSelectOption[]>(
+    () =>
+      value.map(
+        (selectedValue) =>
+          options.find((option) => option.value === selectedValue) ??
+          pickedOptions.get(selectedValue) ?? { label: selectedValue, value: selectedValue },
+      ),
+    [options, value, pickedOptions],
+  );
+
+  const items = useMemo<SearchSelectOption[]>(() => {
+    const missing = selected.filter((option) => !options.some((o) => o.value === option.value));
+    return missing.length === 0 ? options : [...missing, ...options];
+  }, [options, selected]);
+
+  const pagination = { onSearchChange, onLoadMore, hasNextPage, isFetchingNextPage };
+  const { handleInputValueChange, handleScroll } = usePaginatedCombobox(pagination);
+
+  const handleChipsInputChange = (next: string, reason: string) => {
+    setQuery(next);
+    handleInputValueChange(next, reason);
+  };
+
+  return (
+    <Combobox
+      multiple
+      items={items}
+      value={selected}
+      onValueChange={(next: SearchSelectOption[]) => {
+        setPickedOptions(new Map(next.map((option) => [option.value, option])));
+        onValueChange(next.map((option) => option.value));
+      }}
+      inputValue={query}
+      onInputValueChange={(next, eventDetails) => handleChipsInputChange(next, eventDetails.reason)}
+      isItemEqualToValue={(a: SearchSelectOption, b: SearchSelectOption) => a.value === b.value}
+      itemToStringLabel={(item: SearchSelectOption) => item.label}
+      filter={null}
+      disabled={disabled}
+    >
+      <ComboboxChips render={<div ref={anchor} />} className={`min-h-8 py-1 text-sm ${className ?? ""}`}>
+        <ComboboxValue>
+          {(selectedItems: SearchSelectOption[]) =>
+            selectedItems.map((option) => (
+              <ComboboxChip key={option.value} aria-label={option.label}>
+                {option.label}
+              </ComboboxChip>
+            ))
+          }
+        </ComboboxValue>
+        <ComboboxChipsInput
+          id={inputId}
+          aria-invalid={ariaInvalid}
+          aria-describedby={ariaDescribedBy}
+          placeholder={placeholder}
+          className="h-5 min-w-24 flex-1 border-0 bg-transparent py-0 text-sm"
+          aria-label={placeholder}
+        />
+      </ComboboxChips>
+      <ComboboxContent anchor={anchor}>
+        <ComboboxEmpty className={errorText == null ? undefined : "text-destructive"}>
+          {errorText ?? (isLoading ? loadingText : emptyText)}
+        </ComboboxEmpty>
+        <ComboboxList onScroll={handleScroll} data-testid="paginated-multi-select-list">
+          {(item: SearchSelectOption) => (
+            <ComboboxItem key={item.value} value={item}>
+              <span className="flex min-w-0 flex-col">
+                <span className="truncate">{item.label}</span>
+                {item.sublabel != null && item.sublabel !== "" && (
+                  <span className="truncate text-xs text-muted-foreground">{item.sublabel}</span>
+                )}
+              </span>
+            </ComboboxItem>
+          )}
+        </ComboboxList>
+        {isFetchingNextPage && (
+          <div className="flex justify-center py-2" data-testid="paginated-multi-select-loading-more">
+            <Loader2 className="size-4 animate-spin text-muted-foreground" />
+          </div>
+        )}
+      </ComboboxContent>
+    </Combobox>
+  );
+}
diff --git a/ui/litellm-dashboard/src/components/shared/PaginatedSearchSelect.tsx b/ui/litellm-dashboard/src/components/shared/PaginatedSearchSelect.tsx
index 14a3280dfc3..6966c669187 100644
--- a/ui/litellm-dashboard/src/components/shared/PaginatedSearchSelect.tsx
+++ b/ui/litellm-dashboard/src/components/shared/PaginatedSearchSelect.tsx
@@ -1,8 +1,7 @@
 "use client";
 
-import { useDebouncedCallback } from "@tanstack/react-pacer/debouncer";
 import { Loader2 } from "lucide-react";
-import { useMemo, type UIEvent } from "react";
+import { useMemo } from "react";
 
 import {
   Combobox,
@@ -12,13 +11,9 @@ import {
   ComboboxItem,
   ComboboxList,
 } from "@/components/ui/combobox";
-import { DEBOUNCE_WAIT_MS } from "@/utils/debounceConstants";
 
 import type { SearchSelectOption } from "./SearchSelect";
-
-const SCROLL_THRESHOLD = 0.8;
-
-const SEARCH_REASONS: ReadonlySet<string> = new Set(["input-change", "input-clear", "clear-press"]);
+import { usePaginatedCombobox } from "./usePaginatedCombobox";
 
 interface PaginatedSearchSelectProps {
   options: SearchSelectOption[];
@@ -70,21 +65,8 @@ export function PaginatedSearchSelect({
     return [selected, ...options];
   }, [options, selected]);
 
-  const debouncedSearch = useDebouncedCallback(onSearchChange, { wait: DEBOUNCE_WAIT_MS });
-
-  const handleInputValueChange = (next: string, reason: string) => {
-    if (!SEARCH_REASONS.has(reason)) return;
-    debouncedSearch(next);
-  };
-
-  const handleScroll = (event: UIEvent<HTMLDivElement>) => {
-    const target = event.currentTarget;
-    if (target.scrollHeight === 0) return;
-    const ratio = (target.scrollTop + target.clientHeight) / target.scrollHeight;
-    if (ratio >= SCROLL_THRESHOLD && hasNextPage && !isFetchingNextPage) {
-      onLoadMore?.();
-    }
-  };
+  const pagination = { onSearchChange, onLoadMore, hasNextPage, isFetchingNextPage };
+  const { handleInputValueChange, handleScroll } = usePaginatedCombobox(pagination);
 
   return (
     <Combobox
diff --git a/ui/litellm-dashboard/src/components/shared/usePaginatedCombobox.ts b/ui/litellm-dashboard/src/components/shared/usePaginatedCombobox.ts
new file mode 100644
index 00000000000..75171d7d75f
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/shared/usePaginatedCombobox.ts
@@ -0,0 +1,42 @@
+"use client";
+
+import { useDebouncedCallback } from "@tanstack/react-pacer/debouncer";
+import type { UIEvent } from "react";
+
+import { DEBOUNCE_WAIT_MS } from "@/utils/debounceConstants";
+
+const SCROLL_THRESHOLD = 0.8;
+
+const SEARCH_REASONS: ReadonlySet<string> = new Set(["input-change", "input-clear", "clear-press"]);
+
+export interface PaginatedComboboxCallbacks {
+  onSearchChange: (query: string) => void;
+  onLoadMore?: () => void;
+  hasNextPage: boolean;
+  isFetchingNextPage: boolean;
+}
+
+export function usePaginatedCombobox({
+  onSearchChange,
+  onLoadMore,
+  hasNextPage,
+  isFetchingNextPage,
+}: PaginatedComboboxCallbacks) {
+  const debouncedSearch = useDebouncedCallback(onSearchChange, { wait: DEBOUNCE_WAIT_MS });
+
+  const handleInputValueChange = (next: string, reason: string) => {
+    if (!SEARCH_REASONS.has(reason)) return;
+    debouncedSearch(next);
+  };
+
+  const handleScroll = (event: UIEvent<HTMLDivElement>) => {
+    const target = event.currentTarget;
+    if (target.scrollHeight === 0) return;
+    const ratio = (target.scrollTop + target.clientHeight) / target.scrollHeight;
+    if (ratio >= SCROLL_THRESHOLD && hasNextPage && !isFetchingNextPage) {
+      onLoadMore?.();
+    }
+  };
+
+  return { handleInputValueChange, handleScroll };
+}