Add Google Vertex AI with renewable ADC (#1193)

## Problem

| Before | After |
| --- | --- |
| FCC supported Google AI Studio API keys but could not route coding
agents through a Google Cloud Vertex AI project. | `vertex/...` routes
through Google's [documented OpenAI-compatible Chat Completions
endpoint](https://cloud.google.com/vertex-ai/generative-ai/docs/start/openai),
using the global endpoint by default or an explicitly configured region.
|
| A pasted Vertex access token would expire, while Application Default
Credentials were not part of provider construction. | FCC loads
[Application Default
Credentials](https://cloud.google.com/docs/authentication/application-default-credentials),
supplies a renewable credential callback to the OpenAI transport,
coalesces concurrent refreshes, and returns typed authentication or
transient failures. |
| Vertex does not expose its model catalog through the compatible OpenAI
`/models` route. | FCC translates its generic discovery operation to
Google's paginated [publisher-model list
API](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/publishers.models/list)
and converts resource names into the model IDs accepted by Chat
Completions. |
| Google thought signatures were owned by the AI Studio adapter even
though Vertex shares the same protocol behavior. | A neutral Google
OpenAI family owns shared thought-signature and request behavior; AI
Studio and Vertex retain separate endpoint and authentication ownership.
|

## Changes

- Added the Vertex provider, `VERTEX_PROJECT_ID`, optional
`VERTEX_LOCATION` and `VERTEX_PROXY`, Admin UI configuration,
model-picker discovery, smoke metadata, and customer setup
documentation.
- Added renewable ADC access tokens with refresh coalescing, proxy-aware
refresh, sanitized failure classification, and project quota headers.
- Added global/regional endpoint composition plus native model-catalog
pagination, strict response validation, response cleanup, and
repeated-page protection.
- Generalized provider readiness around declared configuration fields so
project-based and multi-field providers no longer pretend every remote
provider is configured by one API key.
- Moved shared Google request quirks out of the Gemini adapter,
preserved AI Studio behavior, and bumped the package to `4.11.0`.

<!-- greptile_comment -->

<details open><summary><h3>Greptile Summary</h3></summary>

This PR adds Google Vertex AI as a new provider using Application
Default Credentials. The main changes are:

- New `vertex` provider with project/location endpoint construction.
- Renewable ADC access-token loading with refresh coalescing and
proxy-aware refresh.
- Native Vertex publisher-model discovery with pagination and response
validation.
- Shared Google OpenAI-compatible request behavior for Gemini and
Vertex.
- Admin UI, settings, smoke config, docs, version, lockfile, and tests
for the new provider.
</details>

<h3>Confidence Score: 5/5</h3>

Safe to merge with low risk.

No blocking correctness or security issues were identified. The new
provider follows the existing provider-runtime and Admin configuration
patterns. Endpoint, auth, model parsing, readiness, docs, version,
lockfile, and tests are updated together.

No files require special attention.

<details><summary><h3><a href="https://www.greptile.com/trex"><img
alt="T-Rex"
src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg"
height="20" align="absmiddle"></a> T-Rex Logs</h3></summary>

**What T-Rex did**
- The T-Rex test suite was executed to validate the code-execution
proof-of-work, generating a full verbose pytest log and recording the
run metadata, and the run completed with EXIT\_CODE: 0.

<a
href="https://app.greptile.com/trex/runs/14991235/artifacts"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifactsDark.svg?v=4"><source
media="(prefers-color-scheme: light)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=4"><img
alt="View all artifacts"
src="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=4"></picture></a>

_{<a href="https://www.greptile.com/trex"><img alt="T-Rex"
src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg"
height="14" align="absmiddle"></a> Ran code and verified through
T-Rex}
</details>

<details open><summary><h3>Important Files Changed</h3></summary>

| Filename | Overview |
|----------|----------|
| src/free_claude_code/providers/vertex/client.py | Adds the Vertex
provider with OpenAI-compatible chat routing and native paginated model
discovery. |
| src/free_claude_code/providers/vertex/auth.py | Implements renewable
ADC token loading, proxy-aware refresh, coalescing, and sanitized auth
failures. |
| src/free_claude_code/providers/vertex/endpoint.py | Builds validated
Vertex global/regional service, chat, and model-list endpoints. |
| src/free_claude_code/providers/vertex/models.py | Parses Vertex
publisher-model pages into OpenAI-compatible model IDs with
malformed-response checks. |
| src/free_claude_code/providers/google_openai/provider.py | Adds shared
Google thought-signature caching and thinking-budget request body
handling. |
| src/free_claude_code/providers/google_openai/quirks.py | Renames
Gemini-specific quirks to shared Google quirks and exposes model-neutral
thinking config helpers. |
| src/free_claude_code/providers/openai_chat/provider.py | Allows
OpenAI-chat providers to pass an async API-key callback into the OpenAI
SDK. |
| src/free_claude_code/providers/runtime/discovery.py | Uses
descriptor-defined readiness to choose providers eligible for model
cache/discovery. |
| src/free_claude_code/config/provider_catalog.py | Adds the Vertex
descriptor and required settings metadata, and makes Cloudflare
readiness require both token and account ID. |
| src/free_claude_code/config/admin/status.py | Generalizes Admin
provider readiness status to use each descriptor's configuration
attributes. |
| src/free_claude_code/config/admin/provider_manifest.py | Adds Admin UI
fields for Vertex project and location alongside generated provider
fields. |
| tests/providers/test_vertex.py | Adds targeted tests for Vertex
endpoints, ADC token refresh, reasoning mapping, and model discovery
pagination. |

</details>

<details open><summary><h3>Sequence Diagram</h3></summary>

<a href="#gh-light-mode-only">

```mermaid
%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant User as User / Admin UI
participant Settings as Settings + Provider Catalog
participant Runtime as Provider Runtime
participant Vertex as VertexProvider
participant ADC as Google ADC
participant OpenAI as OpenAI-compatible Chat Endpoint
participant Models as Vertex Publisher Models API

User->>Settings: Set VERTEX_PROJECT_ID / VERTEX_LOCATION / VERTEX_PROXY
Settings->>Runtime: Descriptor reports vertex configured by project id
Runtime->>Vertex: Construct with project, location, proxy, rate limiter
Vertex->>ADC: Load/refresh Application Default Credentials
ADC-->>Vertex: Renewable access token
Vertex->>OpenAI: Stream chat completion with bearer token + x-goog-user-project
OpenAI-->>Vertex: Streaming chat chunks
Vertex-->>Runtime: Normalized provider stream
Runtime->>Vertex: Refresh model list
Vertex->>Models: GET paginated publishers/google/models
Models-->>Vertex: publisherModels + nextPageToken
Vertex-->>Runtime: Prefixed model IDs for cache/model picker
```

</a>
<a href="#gh-dark-mode-only">

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant User as User / Admin UI
participant Settings as Settings + Provider Catalog
participant Runtime as Provider Runtime
participant Vertex as VertexProvider
participant ADC as Google ADC
participant OpenAI as OpenAI-compatible Chat Endpoint
participant Models as Vertex Publisher Models API

User->>Settings: Set VERTEX_PROJECT_ID / VERTEX_LOCATION / VERTEX_PROXY
Settings->>Runtime: Descriptor reports vertex configured by project id
Runtime->>Vertex: Construct with project, location, proxy, rate limiter
Vertex->>ADC: Load/refresh Application Default Credentials
ADC-->>Vertex: Renewable access token
Vertex->>OpenAI: Stream chat completion with bearer token + x-goog-user-project
OpenAI-->>Vertex: Streaming chat chunks
Vertex-->>Runtime: Normalized provider stream
Runtime->>Vertex: Refresh model list
Vertex->>Models: GET paginated publishers/google/models
Models-->>Vertex: publisherModels + nextPageToken
Vertex-->>Runtime: Prefixed model IDs for cache/model picker
```

</a>
</details>

_{Reviews (1): Last reviewed commit: ["feat: add Google Vertex AI
provider"](https://github.com/alishahryar1/free-claude-code/commit/97e753f0772e60377865876ca59b2fd8888d922e)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=45405432)}

<!-- /greptile_comment -->

.env.example

@@ -76,6 +76,12 @@ CLOUDFLARE_ACCOUNT_ID=""
 GEMINI_API_KEY=""
 
 
+# Google Vertex AI (uses Application Default Credentials; no API key)
+# Local setup: gcloud auth application-default login
+VERTEX_PROJECT_ID=""
+VERTEX_LOCATION="global"
+
+
 # Groq Cloud (OpenAI-compatible Chat Completions; see https://console.groq.com/docs/openai)
 GROQ_API_KEY=""
 
@@ -106,7 +112,7 @@ OLLAMA_BASE_URL="http://localhost:11434"
 
 # All Claude model requests are mapped to these models, plain model is fallback
 # Format: provider_type/model/name
-# Valid providers: "nvidia_nim" | "open_router" | "gemini" | "deepseek" | "mistral" | "mistral_codestral" | "opencode" | "opencode_go" | "vercel" | "bedrock" | "huggingface" | "cohere" | "github_models" | "wafer" | "kimi" | "kimi_code" | "minimax" | "cerebras" | "groq" | "sambanova" | "fireworks" | "cloudflare" | "zai" | "ollama_cloud" | "lmstudio" | "llamacpp" | "ollama"
+# Valid providers: "nvidia_nim" | "open_router" | "gemini" | "vertex" | "deepseek" | "mistral" | "mistral_codestral" | "opencode" | "opencode_go" | "vercel" | "bedrock" | "huggingface" | "cohere" | "github_models" | "wafer" | "kimi" | "kimi_code" | "minimax" | "cerebras" | "groq" | "sambanova" | "fireworks" | "cloudflare" | "zai" | "ollama_cloud" | "lmstudio" | "llamacpp" | "ollama"
 MODEL_FABLE=
 MODEL_OPUS=
 MODEL_SONNET=
@@ -141,6 +147,7 @@ FCC_SMOKE_MODEL_ZAI=
 FCC_SMOKE_MODEL_FIREWORKS=
 FCC_SMOKE_MODEL_CLOUDFLARE=
 FCC_SMOKE_MODEL_GEMINI=
+FCC_SMOKE_MODEL_VERTEX=
 FCC_SMOKE_MODEL_GROQ=
 FCC_SMOKE_MODEL_SAMBANOVA=
 FCC_SMOKE_MODEL_CEREBRAS=
@@ -184,6 +191,7 @@ ZAI_PROXY=""
 FIREWORKS_PROXY=""
 CLOUDFLARE_PROXY=""
 GEMINI_PROXY=""
+VERTEX_PROXY=""
 GROQ_PROXY=""
 SAMBANOVA_PROXY=""
 CEREBRAS_PROXY=""

ARCHITECTURE.md

@@ -490,6 +490,10 @@ request-scoped policy passed to execution.
 
 Provider model discovery and optional thinking metadata live in the
 application-level catalog owned by `ProviderRuntimeManager`.
+Discovery is an adapter operation, not an assumption that every upstream has an
+OpenAI `/models` route. For example, Vertex translates that operation to
+Google's paginated `publishers/google/models` API and converts publisher resource
+names into the exact model IDs accepted by its OpenAI-compatible endpoint.
 `ProviderModelInfo.supports_thinking` alone owns discovered per-model thinking
 support for model-list presentation; it does not select request behavior.
 Provider adapters must never branch on upstream model names or versions to
@@ -508,8 +512,10 @@ passes it as `model_catalog_json`. Codex users open the native picker with
 Provider metadata is neutral and centralized in
 [config/provider_catalog.py](src/free_claude_code/config/provider_catalog.py). Each
 `ProviderDescriptor` declares provider ID, display name, locality, credential env
-var, default base URL, settings attribute names, and proxy support. It does not
-select a concrete adapter.
+var, default base URL, settings attribute names, configuration readiness, and
+proxy support. Readiness may require multiple ordinary settings or a non-secret
+project ID; it is not inferred exclusively from API-key presence. The catalog
+does not select a concrete adapter.
 
 [providers/runtime/](src/free_claude_code/providers/runtime/) owns construction details for one
 closable provider generation: construction policy, resolved provider
@@ -554,7 +560,7 @@ compatibility layer.
 - `BaseProvider`: the abstract implementation base for cleanup, model listing,
   explicit preflight, and `stream_response()`.
 
-There is one upstream provider family:
+There is one upstream transport family:
 [providers/openai_chat/](src/free_claude_code/providers/openai_chat/) implements the concrete
 `OpenAIChatProvider` used by every OpenAI-compatible `/chat/completions`
 upstream. `OpenAIChatProfile` contains immutable request policy, an explicit
@@ -566,6 +572,16 @@ owns the exactly typed private per-request runner, recovery operations, tool-cal
 assembly, and streamed usage handling. No obsolete generic transport namespace
 or untyped provider backchannel remains.
 
+[providers/google_openai/](src/free_claude_code/providers/google_openai/) owns the
+Google-specific protocol behavior shared by AI Studio and Vertex AI: literal
+Google `extra_body` construction, thought-signature replay, and thinking-budget
+encoding. Neither concrete provider imports from the other. AI Studio owns its
+API-key endpoint; [providers/vertex/](src/free_claude_code/providers/vertex/)
+owns project/location endpoint composition, renewable Application Default
+Credentials, and translation of Google's native publisher-model catalog. The
+OpenAI transport receives a callable credential source, so access-token refresh
+does not require rebuilding provider generations or persisting ephemeral tokens.
+
 `OpenAIChatProvider` explicitly implements preflight by constructing the same
 upstream request body it will later stream. `BaseProvider` makes that operation
 abstract, so a new provider cannot silently omit the commit-boundary validation.

README.md

@@ -140,6 +140,7 @@ Enter the listed setting in the Admin UI, open **Model Config**, then search the
 | [NVIDIA NIM](https://build.nvidia.com/settings/api-keys) | `NVIDIA_NIM_API_KEY` | `nvidia_nim/nvidia/nemotron-3-super-120b-a12b` |
 | [OpenRouter](https://openrouter.ai/keys) | `OPENROUTER_API_KEY` | `open_router/openrouter/free` |
 | [Google AI Studio (Gemini)](https://aistudio.google.com/apikey) | `GEMINI_API_KEY` | `gemini/models/gemini-3.1-flash-lite` |
+| [Google Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/start/openai) | `VERTEX_PROJECT_ID` + ADC | `vertex/google/gemini-3.5-flash` |
 | [DeepSeek](https://platform.deepseek.com/api_keys) | `DEEPSEEK_API_KEY` | `deepseek/deepseek-chat` |
 | [Mistral La Plateforme](https://console.mistral.ai/) | `MISTRAL_API_KEY` | `mistral/devstral-small-latest` |
 | [Mistral Codestral](https://console.mistral.ai/) | `CODESTRAL_API_KEY` | `mistral_codestral/codestral-latest` |
@@ -175,6 +176,11 @@ Important provider notes:
 - Amazon Bedrock uses its Mantle OpenAI-compatible endpoint. Set
   `BEDROCK_BASE_URL` to the endpoint for the same region as the API key and
   select one of the models returned by FCC's model picker.
+- Vertex AI uses Google Application Default Credentials instead of an API key.
+  Locally, run `gcloud auth application-default login` once; service-account
+  files and attached service accounts also work. Set `VERTEX_PROJECT_ID`, and
+  optionally change `VERTEX_LOCATION` from its `global` default. FCC refreshes
+  expiring access tokens automatically.
 - Cloudflare requires both its API token and account ID.
 - Ollama Cloud connects directly to `ollama.com`; use the exact model IDs shown
   by FCC's model picker. Local Ollama remains available through the separate

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "free-claude-code"
-version = "4.10.0"
+version = "4.11.0"
 description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
 readme = "README.md"
 requires-python = ">=3.14.0"
@@ -23,6 +23,8 @@ dependencies = [
     "loguru>=0.7.0",
     "aiohttp>=3.14.1",
     "jsonschema>=4.25.0",
+    "google-auth[requests]>=2.40.0",
+    "requests[socks]>=2.32.0",
 ]
 
 [project.scripts]

smoke/lib/config.py

@@ -11,6 +11,7 @@ from free_claude_code.config.provider_catalog import (
     SUPPORTED_PROVIDER_IDS,
 )
 from free_claude_code.config.settings import Settings, get_settings
+from free_claude_code.providers.runtime.config import has_provider_configuration
 
 DEFAULT_TARGETS = frozenset(
     {
@@ -65,6 +66,7 @@ PROVIDER_SMOKE_DEFAULT_MODELS: dict[str, str] = {
     "github_models": "github_models/openai/gpt-4.1",
     "zai": "zai/glm-5.2",
     "gemini": "gemini/models/gemini-3.1-flash-lite",
+    "vertex": "vertex/google/gemini-3.5-flash",
     "groq": "groq/llama-3.3-70b-versatile",
     "sambanova": "sambanova/Meta-Llama-3.3-70B-Instruct",
     "cerebras": "cerebras/llama3.1-8b",
@@ -252,21 +254,10 @@ class SmokeConfig:
         return bool(os.getenv(f"FCC_SMOKE_MODEL_{provider.upper()}"))
 
     def has_provider_configuration(self, provider: str) -> bool:
-        if provider == "cloudflare":
-            return bool(
-                self.settings.cloudflare_api_token.strip()
-                and self.settings.cloudflare_account_id.strip()
-            )
         descriptor = PROVIDER_CATALOG.get(provider)
         if descriptor is None:
             return False
-        if descriptor.credential_attr:
-            credential = getattr(self.settings, descriptor.credential_attr, "")
-            return isinstance(credential, str) and bool(credential.strip())
-        if descriptor.base_url_attr:
-            base_url = getattr(self.settings, descriptor.base_url_attr, "")
-            return isinstance(base_url, str) and bool(base_url.strip())
-        return descriptor.static_credential is not None
+        return has_provider_configuration(descriptor, self.settings)
 
 
 def _parse_csv(raw: str | None) -> frozenset[str]:

src/free_claude_code/api/admin_static/admin.js

@@ -60,7 +60,7 @@ function sourceText(field) {
 
 function statusClass(status) {
   if (["configured", "reachable", "running"].includes(status)) return "ok";
-  if (["missing_key", "missing_url", "unknown"].includes(status)) return "warn";
+  if (["missing_key", "missing_config", "missing_url", "unknown"].includes(status)) return "warn";
   if (["offline", "error"].includes(status)) return "error";
   return "neutral";
 }
@@ -162,7 +162,7 @@ function renderProviders(providerStatus) {
     meta.textContent =
       provider.kind === "local"
         ? provider.base_url || "No local URL configured"
-        : provider.credential_env;
+        : provider.configuration;
 
     const button = document.createElement("button");
     button.type = "button";

src/free_claude_code/config/admin/provider_manifest.py

@@ -143,6 +143,7 @@ def provider_field_specs() -> tuple[dict[str, Any], ...]:
     return (
         *_credential_field_specs(),
         *_cloudflare_account_field_specs(),
+        *_vertex_field_specs(),
         *_base_url_field_specs(),
         *_proxy_field_specs(),
     )
@@ -202,6 +203,32 @@ def _cloudflare_account_field_specs() -> tuple[dict[str, Any], ...]:
     )
 
 
+def _vertex_field_specs() -> tuple[dict[str, Any], ...]:
+    return (
+        {
+            "key": "VERTEX_PROJECT_ID",
+            "label": "Google Cloud Project ID",
+            "section_id": "providers",
+            "settings_attr": "vertex_project_id",
+            "description": (
+                "Google Cloud project used for Vertex AI. Authentication uses "
+                "Application Default Credentials (ADC)."
+            ),
+        },
+        {
+            "key": "VERTEX_LOCATION",
+            "label": "Vertex AI Location",
+            "section_id": "providers",
+            "settings_attr": "vertex_location",
+            "default": "global",
+            "description": (
+                "Use global for the global Vertex AI endpoint or a region such as "
+                "us-central1."
+            ),
+        },
+    )
+
+
 def _proxy_field_specs() -> tuple[dict[str, Any], ...]:
     specs: list[dict[str, Any]] = []
     for descriptor in PROVIDER_CATALOG.values():

src/free_claude_code/config/admin/status.py

@@ -30,16 +30,35 @@ def provider_config_status(
             )
             continue
 
-        value = str(state.get(descriptor.credential_env, {}).get("value", ""))
-        configured = bool(value.strip())
+        configured = all(
+            _value_for_settings_attr(state, attr).strip()
+            for attr in descriptor.configuration_attrs()
+        )
+        configuration = " + ".join(
+            _field_key_for_settings_attr(attr)
+            for attr in descriptor.configuration_attrs()
+        )
+        missing_key = descriptor.credential_env is not None
         statuses.append(
             {
                 "provider_id": provider_id,
                 "display_name": descriptor.display_name,
                 "kind": "remote",
-                "status": "configured" if configured else "missing_key",
-                "label": "Configured" if configured else "Missing key",
-                "credential_env": descriptor.credential_env,
+                "status": (
+                    "configured"
+                    if configured
+                    else "missing_key"
+                    if missing_key
+                    else "missing_config"
+                ),
+                "label": (
+                    "Configured"
+                    if configured
+                    else "Missing key"
+                    if missing_key
+                    else "Missing configuration"
+                ),
+                "configuration": configuration,
             }
         )
     return statuses
@@ -52,3 +71,10 @@ def _value_for_settings_attr(
         if field.settings_attr == settings_attr:
             return str(state.get(field.key, {}).get("value", field.default))
     return ""
+
+
+def _field_key_for_settings_attr(settings_attr: str) -> str:
+    for field in FIELDS:
+        if field.settings_attr == settings_attr:
+            return field.key
+    raise AssertionError(f"No admin field owns settings attribute {settings_attr!r}")

src/free_claude_code/config/provider_catalog.py

@@ -40,6 +40,8 @@ GITHUB_MODELS_DEFAULT_BASE = "https://models.github.ai/inference"
 ZAI_DEFAULT_BASE = "https://api.z.ai/api/coding/paas/v4"
 # Google AI Studio Gemini API OpenAI-compat layer (not Vertex AI).
 GEMINI_DEFAULT_BASE = "https://generativelanguage.googleapis.com/v1beta/openai/"
+# Vertex AI API root. The provider owns project/location endpoint composition.
+VERTEX_AI_API_ROOT = "https://aiplatform.googleapis.com"
 GROQ_DEFAULT_BASE = "https://api.groq.com/openai/v1"
 CEREBRAS_DEFAULT_BASE = "https://api.cerebras.ai/v1"
 SAMBANOVA_DEFAULT_BASE = "https://api.sambanova.ai/v1"
@@ -59,6 +61,17 @@ class ProviderDescriptor:
     default_base_url: str | None = None
     base_url_attr: str | None = None
     proxy_attr: str | None = None
+    required_settings_attrs: tuple[str, ...] = ()
+
+    def configuration_attrs(self) -> tuple[str, ...]:
+        """Return settings fields whose non-empty values configure this provider."""
+        if self.required_settings_attrs:
+            return self.required_settings_attrs
+        if self.credential_attr is not None:
+            return (self.credential_attr,)
+        if self.base_url_attr is not None:
+            return (self.base_url_attr,)
+        return ()
 
 
 PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
@@ -89,6 +102,17 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
         default_base_url=GEMINI_DEFAULT_BASE,
         proxy_attr="gemini_proxy",
     ),
+    "vertex": ProviderDescriptor(
+        provider_id="vertex",
+        display_name="Google Vertex AI",
+        credential_url=(
+            "https://cloud.google.com/docs/authentication/"
+            "set-up-adc-local-dev-environment"
+        ),
+        default_base_url=VERTEX_AI_API_ROOT,
+        proxy_attr="vertex_proxy",
+        required_settings_attrs=("vertex_project_id",),
+    ),
     "deepseek": ProviderDescriptor(
         provider_id="deepseek",
         display_name="DeepSeek",
@@ -259,6 +283,10 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
         credential_attr="cloudflare_api_token",
         default_base_url=CLOUDFLARE_AI_REST_ROOT,
         proxy_attr="cloudflare_proxy",
+        required_settings_attrs=(
+            "cloudflare_api_token",
+            "cloudflare_account_id",
+        ),
     ),
     "zai": ProviderDescriptor(
         provider_id="zai",

src/free_claude_code/config/settings.py

@@ -91,6 +91,10 @@ class Settings(BaseSettings):
     # ==================== Google Gemini (Google AI Studio) ====================
     gemini_api_key: str = Field(default="", validation_alias="GEMINI_API_KEY")
 
+    # ==================== Google Vertex AI ====================
+    vertex_project_id: str = Field(default="", validation_alias="VERTEX_PROJECT_ID")
+    vertex_location: str = Field(default="global", validation_alias="VERTEX_LOCATION")
+
     # ==================== Groq (OpenAI-compatible) ====================
     groq_api_key: str = Field(default="", validation_alias="GROQ_API_KEY")
 
@@ -170,6 +174,7 @@ class Settings(BaseSettings):
     fireworks_proxy: str = Field(default="", validation_alias="FIREWORKS_PROXY")
     cloudflare_proxy: str = Field(default="", validation_alias="CLOUDFLARE_PROXY")
     gemini_proxy: str = Field(default="", validation_alias="GEMINI_PROXY")
+    vertex_proxy: str = Field(default="", validation_alias="VERTEX_PROXY")
     groq_proxy: str = Field(default="", validation_alias="GROQ_PROXY")
     cerebras_proxy: str = Field(default="", validation_alias="CEREBRAS_PROXY")
     ollama_cloud_proxy: str = Field(default="", validation_alias="OLLAMA_CLOUD_PROXY")

src/free_claude_code/providers/gemini/client.py

@@ -1,28 +1,16 @@
 """Google AI Studio Gemini provider (OpenAI-compatible chat completions)."""
 
-from copy import deepcopy
-from typing import Any
-
 from free_claude_code.core.anthropic import ReasoningReplayMode
-from free_claude_code.core.anthropic.models import MessagesRequest
-from free_claude_code.core.reasoning import (
-    DEFAULT_REASONING_POLICY,
-    ReasoningEffort,
-    ReasoningPolicy,
-)
+from free_claude_code.core.reasoning import ReasoningEffort
 from free_claude_code.providers.base import ProviderConfig
+from free_claude_code.providers.google_openai import GoogleOpenAIProvider
 from free_claude_code.providers.openai_chat import (
     NamedEffortReasoning,
     OpenAIChatProfile,
-    OpenAIChatProvider,
     OpenAIChatRequestPolicy,
-    build_openai_chat_request_body,
 )
 from free_claude_code.providers.rate_limit import ProviderRateLimiter
 
-from .quirks import apply_gemini_request_quirks
-
-_MAX_TOOL_CALL_EXTRA_CONTENT_CACHE = 4096
 _REQUEST_POLICY = OpenAIChatRequestPolicy(
     provider_name="GEMINI",
     reasoning_replay=ReasoningReplayMode.REASONING_CONTENT,
@@ -43,7 +31,7 @@ _PROFILE = OpenAIChatProfile(
 )
 
 
-class GeminiProvider(OpenAIChatProvider):
+class GeminiProvider(GoogleOpenAIProvider):
     """Gemini API using ``https://generativelanguage.googleapis.com/v1beta/openai/``."""
 
     def __init__(self, config: ProviderConfig, *, rate_limiter: ProviderRateLimiter):
@@ -52,38 +40,3 @@ class GeminiProvider(OpenAIChatProvider):
             profile=_PROFILE,
             rate_limiter=rate_limiter,
         )
-        self._tool_call_extra_content_by_id: dict[str, dict[str, Any]] = {}
-
-    def _record_tool_call_extra_content(
-        self, tool_call_id: str, extra_content: dict[str, Any]
-    ) -> None:
-        if (
-            tool_call_id not in self._tool_call_extra_content_by_id
-            and len(self._tool_call_extra_content_by_id)
-            >= _MAX_TOOL_CALL_EXTRA_CONTENT_CACHE
-        ):
-            self._tool_call_extra_content_by_id.pop(
-                next(iter(self._tool_call_extra_content_by_id))
-            )
-        self._tool_call_extra_content_by_id[tool_call_id] = deepcopy(extra_content)
-
-    def _build_request_body(
-        self,
-        request: MessagesRequest,
-        *,
-        reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
-    ) -> dict:
-        return build_openai_chat_request_body(
-            request,
-            reasoning=reasoning,
-            policy=_REQUEST_POLICY,
-            postprocessors=(
-                lambda body, request_data, policy: apply_gemini_request_quirks(
-                    body,
-                    request_data,
-                    policy,
-                    tool_call_extra_content_by_id=self._tool_call_extra_content_by_id,
-                ),
-                _PROFILE.apply_reasoning,
-            ),
-        )

src/free_claude_code/providers/google_openai/__init__.py

@@ -0,0 +1,10 @@
+"""Shared Google OpenAI-compatible provider family."""
+
+from .provider import GoogleOpenAIProvider, GoogleThinkingBudgetReasoning
+from .quirks import GOOGLE_SKIP_THOUGHT_SIGNATURE_VALIDATOR
+
+__all__ = [
+    "GOOGLE_SKIP_THOUGHT_SIGNATURE_VALIDATOR",
+    "GoogleOpenAIProvider",
+    "GoogleThinkingBudgetReasoning",
+]

src/free_claude_code/providers/google_openai/provider.py

@@ -0,0 +1,99 @@
+"""Shared Google behavior for OpenAI-compatible Gemini endpoints."""
+
+from collections.abc import Mapping
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any
+
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.reasoning import (
+    DEFAULT_REASONING_POLICY,
+    ReasoningControl,
+    ReasoningPolicy,
+)
+from free_claude_code.providers.base import ProviderConfig
+from free_claude_code.providers.openai_chat import (
+    OpenAIAsyncCredentialProvider,
+    OpenAIChatProfile,
+    OpenAIChatProvider,
+    build_openai_chat_request_body,
+)
+from free_claude_code.providers.rate_limit import ProviderRateLimiter
+
+from .quirks import apply_google_request_quirks, google_thinking_config
+
+_MAX_TOOL_CALL_EXTRA_CONTENT_CACHE = 4096
+
+
+@dataclass(frozen=True, slots=True)
+class GoogleThinkingBudgetReasoning:
+    """Encode FCC reasoning intent in Google's model-neutral thinking budget."""
+
+    def encode(self, body: dict[str, Any], policy: ReasoningPolicy) -> None:
+        if policy.control is ReasoningControl.OFF:
+            thinking = google_thinking_config(body)
+            thinking["thinking_budget"] = 0
+            thinking["include_thoughts"] = False
+            return
+        budget = policy.numeric_budget_tokens
+        if budget is None:
+            return
+        thinking = google_thinking_config(body)
+        thinking.setdefault("thinking_budget", budget)
+        thinking.setdefault("include_thoughts", True)
+
+
+class GoogleOpenAIProvider(OpenAIChatProvider):
+    """Shared thought-signature and request behavior for Google Gemini APIs."""
+
+    def __init__(
+        self,
+        config: ProviderConfig,
+        *,
+        profile: OpenAIChatProfile,
+        rate_limiter: ProviderRateLimiter,
+        api_key_provider: OpenAIAsyncCredentialProvider | None = None,
+        default_headers: Mapping[str, str] | None = None,
+    ) -> None:
+        super().__init__(
+            config,
+            profile=profile,
+            rate_limiter=rate_limiter,
+            api_key_provider=api_key_provider,
+            default_headers=default_headers,
+        )
+        self._tool_call_extra_content_by_id: dict[str, dict[str, Any]] = {}
+
+    def _record_tool_call_extra_content(
+        self, tool_call_id: str, extra_content: dict[str, Any]
+    ) -> None:
+        if (
+            tool_call_id not in self._tool_call_extra_content_by_id
+            and len(self._tool_call_extra_content_by_id)
+            >= _MAX_TOOL_CALL_EXTRA_CONTENT_CACHE
+        ):
+            self._tool_call_extra_content_by_id.pop(
+                next(iter(self._tool_call_extra_content_by_id))
+            )
+        self._tool_call_extra_content_by_id[tool_call_id] = deepcopy(extra_content)
+
+    def _build_request_body(
+        self,
+        request: MessagesRequest,
+        *,
+        reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+    ) -> dict[str, Any]:
+        return build_openai_chat_request_body(
+            request,
+            reasoning=reasoning,
+            policy=self._profile.request_policy,
+            postprocessors=(
+                lambda body, request_data, policy: apply_google_request_quirks(
+                    body,
+                    request_data,
+                    policy,
+                    tool_call_extra_content_by_id=(self._tool_call_extra_content_by_id),
+                ),
+                self._profile.apply_reasoning,
+            ),
+        )

src/free_claude_code/providers/{gemini → google_openai}/quirks.py

@@ -1,4 +1,4 @@
-"""Gemini request-body quirks for the shared OpenAI-chat provider."""
+"""Google Gemini extensions shared by Google OpenAI-compatible endpoints."""
 
 from copy import deepcopy
 from typing import Any, cast
@@ -6,10 +6,10 @@ from typing import Any, cast
 from free_claude_code.core.anthropic.models import MessagesRequest
 from free_claude_code.core.reasoning import ReasoningPolicy
 
-GEMINI_SKIP_THOUGHT_SIGNATURE_VALIDATOR = "skip_thought_signature_validator"
+GOOGLE_SKIP_THOUGHT_SIGNATURE_VALIDATOR = "skip_thought_signature_validator"
 
 
-def apply_gemini_request_quirks(
+def apply_google_request_quirks(
     body: dict[str, Any],
     request_data: MessagesRequest,
     reasoning: ReasoningPolicy,
@@ -23,17 +23,31 @@ def apply_gemini_request_quirks(
         extra_body.update(deepcopy(request_extra))
 
     if reasoning.requests_reasoning:
-        _apply_thinking_config(extra_body)
+        _thinking_config(extra_body).setdefault("include_thoughts", True)
 
     if extra_body:
         body["extra_body"] = extra_body
 
-    _apply_gemini_tool_call_signatures(
+    _apply_google_tool_call_signatures(
         body,
         tool_call_extra_content_by_id=tool_call_extra_content_by_id,
     )
 
 
+def google_thinking_config(body: dict[str, Any]) -> dict[str, Any]:
+    """Return Google's literal ``extra_body.google.thinking_config`` object."""
+    extra_body = _ensure_dict(body, "extra_body")
+    return _thinking_config(extra_body)
+
+
+def _thinking_config(extra_body: dict[str, Any]) -> dict[str, Any]:
+    # OpenAI's SDK merges its ``extra_body`` argument into the request JSON.
+    # Google expects its extension fields under a literal JSON ``extra_body`` key.
+    literal_extra_body = _ensure_dict(extra_body, "extra_body")
+    google_section = _ensure_dict(literal_extra_body, "google")
+    return _ensure_dict(google_section, "thinking_config")
+
+
 def _ensure_dict(container: dict[str, Any], key: str) -> dict[str, Any]:
     value = container.get(key)
     if isinstance(value, dict):
@@ -43,15 +57,6 @@ def _ensure_dict(container: dict[str, Any], key: str) -> dict[str, Any]:
     return nested
 
 
-def _apply_thinking_config(extra_body: dict[str, Any]) -> None:
-    # OpenAI's SDK merges its ``extra_body`` argument into the request JSON.
-    # Google expects its extension fields under a literal JSON ``extra_body`` key.
-    literal_extra_body = _ensure_dict(extra_body, "extra_body")
-    google_section = _ensure_dict(literal_extra_body, "google")
-    thinking_cfg = _ensure_dict(google_section, "thinking_config")
-    thinking_cfg.setdefault("include_thoughts", True)
-
-
 def _thought_signature_from_extra_content(extra_content: Any) -> str | None:
     if not isinstance(extra_content, dict):
         return None
@@ -145,11 +150,11 @@ def _apply_missing_current_turn_signatures(messages: list[Any]) -> None:
         if _tool_call_thought_signature(first_tool_call):
             continue
         _set_tool_call_thought_signature(
-            first_tool_call, GEMINI_SKIP_THOUGHT_SIGNATURE_VALIDATOR
+            first_tool_call, GOOGLE_SKIP_THOUGHT_SIGNATURE_VALIDATOR
         )
 
 
-def _apply_gemini_tool_call_signatures(
+def _apply_google_tool_call_signatures(
     body: dict[str, Any],
     *,
     tool_call_extra_content_by_id: dict[str, dict[str, Any]] | None,

src/free_claude_code/providers/openai_chat/__init__.py

@@ -6,7 +6,7 @@ from free_claude_code.providers.rate_limit import ProviderRateLimiter
 from .base_url import openai_v1_base_url
 from .extra_body import validate_extra_body_does_not_override_canonical_fields
 from .profiles import OPENAI_CHAT_PROFILES, OpenAIChatProfile
-from .provider import OpenAIChatProvider
+from .provider import OpenAIAsyncCredentialProvider, OpenAIChatProvider
 from .reasoning import (
     NO_REASONING,
     ChatTemplateReasoning,
@@ -41,6 +41,7 @@ __all__ = [
     "OPENAI_CHAT_PROFILES",
     "ChatTemplateReasoning",
     "NamedEffortReasoning",
+    "OpenAIAsyncCredentialProvider",
     "OpenAIChatProfile",
     "OpenAIChatProvider",
     "OpenAIChatRequestPolicy",

src/free_claude_code/providers/openai_chat/provider.py

@@ -3,7 +3,7 @@
 import asyncio
 import sys
 import uuid
-from collections.abc import AsyncIterator, Iterator, Mapping
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Mapping
 from typing import Any
 
 import httpx
@@ -63,6 +63,8 @@ from .usage import (
     usage_int,
 )
 
+OpenAIAsyncCredentialProvider = Callable[[], Awaitable[str]]
+
 
 class OpenAIChatProvider(BaseProvider):
     """OpenAI-compatible ``/chat/completions`` provider configured by a profile."""
@@ -74,6 +76,7 @@ class OpenAIChatProvider(BaseProvider):
         profile: OpenAIChatProfile,
         rate_limiter: ProviderRateLimiter,
         default_headers: Mapping[str, str] | None = None,
+        api_key_provider: OpenAIAsyncCredentialProvider | None = None,
     ):
         super().__init__(config)
         self._profile = profile
@@ -96,7 +99,7 @@ class OpenAIChatProvider(BaseProvider):
                 ),
             )
         self._client = AsyncOpenAI(
-            api_key=self._api_key,
+            api_key=api_key_provider or self._api_key,
             base_url=self._base_url,
             max_retries=0,
             default_headers=default_headers,

src/free_claude_code/providers/runtime/config.py

@@ -23,6 +23,16 @@ def provider_credential(descriptor: ProviderDescriptor, settings: Settings) -> s
     return ""
 
 
+def has_provider_configuration(
+    descriptor: ProviderDescriptor, settings: Settings
+) -> bool:
+    """Return whether all provider-defining settings are present."""
+    attrs = descriptor.configuration_attrs()
+    if attrs:
+        return all(string_setting(settings, attr).strip() for attr in attrs)
+    return descriptor.static_credential is not None
+
+
 def require_provider_credential(
     descriptor: ProviderDescriptor, credential: str
 ) -> None:

src/free_claude_code/providers/runtime/discovery.py

@@ -14,7 +14,7 @@ from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
 from free_claude_code.config.settings import Settings
 from free_claude_code.providers.base import BaseProvider
 
-from .config import provider_credential
+from .config import has_provider_configuration
 from .model_cache import ProviderModelCache
 from .validation import provider_query_failure_reason
 
@@ -31,11 +31,7 @@ def model_cache_provider_ids_for_settings(settings: Settings) -> tuple[str, ...]
     return tuple(
         provider_id
         for provider_id, descriptor in PROVIDER_CATALOG.items()
-        if descriptor.local
-        or (
-            descriptor.credential_env is not None
-            and provider_credential(descriptor, settings).strip()
-        )
+        if has_provider_configuration(descriptor, settings)
     )
 
 

src/free_claude_code/providers/runtime/factory.py

@@ -97,6 +97,21 @@ def _create_gemini(
     return GeminiProvider(config, rate_limiter=rate_limiter)
 
 
+def _create_vertex(
+    config: ProviderConfig,
+    settings: Settings,
+    rate_limiter: ProviderRateLimiter,
+) -> BaseProvider:
+    from free_claude_code.providers.vertex import VertexProvider
+
+    return VertexProvider(
+        config,
+        project_id=settings.vertex_project_id,
+        location=settings.vertex_location,
+        rate_limiter=rate_limiter,
+    )
+
+
 def _create_github_models(
     config: ProviderConfig,
     _settings: Settings,
@@ -115,6 +130,7 @@ _SPECIAL_PROVIDER_FACTORIES: dict[str, ProviderFactory] = {
     "lmstudio": _create_lmstudio,
     "cloudflare": _create_cloudflare,
     "gemini": _create_gemini,
+    "vertex": _create_vertex,
     "github_models": _create_github_models,
 }
 

src/free_claude_code/providers/vertex/__init__.py

@@ -0,0 +1,5 @@
+"""Google Vertex AI OpenAI-compatible adapter."""
+
+from .client import VertexProvider
+
+__all__ = ["VertexProvider"]

src/free_claude_code/providers/vertex/auth.py

@@ -0,0 +1,105 @@
+"""Renewable Google Application Default Credentials for Vertex AI."""
+
+import asyncio
+from collections.abc import Callable
+
+import google.auth
+import requests
+from google.auth.credentials import Credentials
+from google.auth.exceptions import (
+    DefaultCredentialsError,
+    GoogleAuthError,
+    RefreshError,
+    TransportError,
+)
+from google.auth.transport.requests import Request
+
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+
+GOOGLE_CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform"
+
+CredentialsLoader = Callable[[], Credentials]
+
+
+def load_application_default_credentials() -> Credentials:
+    """Load ADC with the scope required by Vertex AI."""
+    credentials, _project = google.auth.default(scopes=(GOOGLE_CLOUD_PLATFORM_SCOPE,))
+    return credentials
+
+
+class GoogleAccessTokenProvider:
+    """Return a valid ADC access token, refreshing it without blocking the event loop."""
+
+    def __init__(
+        self,
+        credentials_loader: CredentialsLoader = load_application_default_credentials,
+        *,
+        proxy: str = "",
+    ) -> None:
+        self._credentials_loader = credentials_loader
+        self._proxy = proxy
+        self._credentials: Credentials | None = None
+        self._refresh_lock = asyncio.Lock()
+
+    async def __call__(self) -> str:
+        credentials = self._credentials
+        if credentials is not None and credentials.valid and credentials.token:
+            return credentials.token
+
+        async with self._refresh_lock:
+            credentials = self._credentials
+            if credentials is not None and credentials.valid and credentials.token:
+                return credentials.token
+            try:
+                if credentials is None:
+                    credentials = await asyncio.to_thread(self._credentials_loader)
+                    self._credentials = credentials
+                if not credentials.valid or not credentials.token:
+                    await asyncio.to_thread(self._refresh, credentials)
+                token = credentials.token
+                if not isinstance(token, str) or not token:
+                    raise RefreshError("Google credentials returned no access token.")
+                return token
+            except ExecutionFailure:
+                raise
+            except GoogleAuthError as exc:
+                raise _google_auth_failure(exc) from exc
+
+    def _refresh(self, credentials: Credentials) -> None:
+        with requests.Session() as session:
+            if self._proxy:
+                session.proxies.update({"http": self._proxy, "https": self._proxy})
+            credentials.refresh(Request(session=session))
+
+
+def _google_auth_failure(exc: GoogleAuthError) -> ExecutionFailure:
+    if isinstance(exc, TransportError) or (
+        isinstance(exc, RefreshError) and bool(getattr(exc, "retryable", False))
+    ):
+        return ExecutionFailure(
+            kind=FailureKind.UNAVAILABLE,
+            status_code=503,
+            message=(
+                "Google authentication is temporarily unavailable while refreshing "
+                "Application Default Credentials."
+            ),
+            retryable=True,
+        )
+    if isinstance(exc, DefaultCredentialsError):
+        message = (
+            "Google Application Default Credentials were not found. Run "
+            "`gcloud auth application-default login`, set "
+            "GOOGLE_APPLICATION_CREDENTIALS, or attach a service account."
+        )
+    else:
+        message = (
+            "Google Application Default Credentials could not be refreshed. "
+            "Reauthenticate with `gcloud auth application-default login` or check "
+            "the configured service account."
+        )
+    return ExecutionFailure(
+        kind=FailureKind.AUTHENTICATION,
+        status_code=401,
+        message=message,
+        retryable=False,
+    )

src/free_claude_code/providers/vertex/client.py

@@ -0,0 +1,126 @@
+"""Google Vertex AI provider using the OpenAI-compatible Chat Completions API."""
+
+from dataclasses import replace
+from typing import Any
+
+import httpx
+
+from free_claude_code.core.anthropic import ReasoningReplayMode
+from free_claude_code.providers.base import ProviderConfig
+from free_claude_code.providers.google_openai import (
+    GoogleOpenAIProvider,
+    GoogleThinkingBudgetReasoning,
+)
+from free_claude_code.providers.http import maybe_await_aclose
+from free_claude_code.providers.model_listing import ModelListResponseError
+from free_claude_code.providers.openai_chat import (
+    OpenAIChatProfile,
+    OpenAIChatRequestPolicy,
+)
+from free_claude_code.providers.rate_limit import ProviderRateLimiter
+
+from .auth import GoogleAccessTokenProvider
+from .endpoint import vertex_openai_base_url, vertex_publisher_models_url
+from .models import extract_vertex_model_page
+
+_REQUEST_POLICY = OpenAIChatRequestPolicy(
+    provider_name="VERTEX",
+    reasoning_replay=ReasoningReplayMode.REASONING_CONTENT,
+)
+_PROFILE = OpenAIChatProfile(_REQUEST_POLICY, GoogleThinkingBudgetReasoning())
+
+
+class VertexProvider(GoogleOpenAIProvider):
+    """Vertex AI Gemini models with renewable ADC and native model discovery."""
+
+    def __init__(
+        self,
+        config: ProviderConfig,
+        *,
+        project_id: str,
+        location: str,
+        rate_limiter: ProviderRateLimiter,
+        access_token_provider: GoogleAccessTokenProvider | None = None,
+    ) -> None:
+        self._project_id = project_id.strip()
+        self._location = location.strip().lower()
+        base_url = vertex_openai_base_url(self._project_id, self._location)
+        self._models_url = vertex_publisher_models_url(self._location)
+        self._access_token_provider = (
+            access_token_provider or GoogleAccessTokenProvider(proxy=config.proxy)
+        )
+        self._model_list_client = httpx.AsyncClient(
+            proxy=config.proxy or None,
+            timeout=httpx.Timeout(
+                config.http_read_timeout,
+                connect=config.http_connect_timeout,
+                read=config.http_read_timeout,
+                write=config.http_write_timeout,
+            ),
+        )
+        super().__init__(
+            replace(config, base_url=base_url),
+            profile=_PROFILE,
+            rate_limiter=rate_limiter,
+            api_key_provider=self._access_token_provider,
+            default_headers={"x-goog-user-project": self._project_id},
+        )
+
+    async def cleanup(self) -> None:
+        """Release both OpenAI-compatible and native model-list clients."""
+        try:
+            await super().cleanup()
+        finally:
+            await self._model_list_client.aclose()
+
+    async def list_model_ids(self) -> frozenset[str]:
+        """List Vertex publisher models and translate their resource names."""
+        model_ids: set[str] = set()
+        page_token: str | None = None
+        seen_page_tokens: set[str] = set()
+        while True:
+            payload = await self._list_model_page(page_token)
+            page_ids, page_token = extract_vertex_model_page(payload)
+            model_ids.update(page_ids)
+            if page_token is None:
+                break
+            if page_token in seen_page_tokens:
+                raise ModelListResponseError(
+                    "VERTEX model-list response is malformed: repeated nextPageToken"
+                )
+            seen_page_tokens.add(page_token)
+        if not model_ids:
+            raise ModelListResponseError(
+                "VERTEX model-list response is malformed: response did not include "
+                "any model ids"
+            )
+        return frozenset(model_ids)
+
+    async def _list_model_page(self, page_token: str | None) -> Any:
+        async def request() -> httpx.Response:
+            token = await self._access_token_provider()
+            response = await self._model_list_client.get(
+                self._models_url,
+                params={"pageToken": page_token} if page_token else None,
+                headers={
+                    "Authorization": f"Bearer {token}",
+                    "x-goog-user-project": self._project_id,
+                },
+            )
+            try:
+                response.raise_for_status()
+            except Exception:
+                await maybe_await_aclose(response)
+                raise
+            return response
+
+        response = await self._rate_limiter.execute_with_retry(request)
+        try:
+            try:
+                return response.json()
+            except ValueError as exc:
+                raise ModelListResponseError(
+                    "VERTEX model-list response is malformed: invalid JSON"
+                ) from exc
+        finally:
+            await maybe_await_aclose(response)

src/free_claude_code/providers/vertex/endpoint.py

@@ -0,0 +1,50 @@
+"""Vertex AI service and OpenAI-compatible endpoint construction."""
+
+import re
+from urllib.parse import quote
+
+from free_claude_code.application.errors import ApplicationUnavailableError
+from free_claude_code.config.provider_catalog import VERTEX_AI_API_ROOT
+
+_LOCATION_PATTERN = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*")
+
+
+def vertex_service_endpoint(location: str) -> str:
+    """Return Google's global or regional Vertex AI service endpoint."""
+    normalized = _validated_location(location)
+    if normalized == "global":
+        return VERTEX_AI_API_ROOT
+    return f"https://{normalized}-aiplatform.googleapis.com"
+
+
+def vertex_openai_base_url(project_id: str, location: str) -> str:
+    """Return the project-scoped Vertex OpenAI-compatible API base URL."""
+    project = project_id.strip()
+    if not project:
+        raise ApplicationUnavailableError(
+            "VERTEX_PROJECT_ID is not set. Add it to your .env file."
+        )
+    normalized_location = _validated_location(location)
+    service_endpoint = vertex_service_endpoint(normalized_location)
+    return (
+        f"{service_endpoint}/v1/projects/{quote(project, safe='')}/locations/"
+        f"{normalized_location}/endpoints/openapi"
+    )
+
+
+def vertex_publisher_models_url(location: str) -> str:
+    """Return Google's native publisher-model listing endpoint."""
+    return f"{vertex_service_endpoint(location)}/v1beta1/publishers/google/models"
+
+
+def _validated_location(location: str) -> str:
+    normalized = location.strip().lower()
+    if not normalized:
+        raise ApplicationUnavailableError(
+            "VERTEX_LOCATION is not set. Use global or a Google Cloud region."
+        )
+    if _LOCATION_PATTERN.fullmatch(normalized) is None:
+        raise ApplicationUnavailableError(
+            "VERTEX_LOCATION must be global or a lowercase Google Cloud region."
+        )
+    return normalized

src/free_claude_code/providers/vertex/models.py

@@ -0,0 +1,52 @@
+"""Vertex publisher-model response parsing."""
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from free_claude_code.providers.model_listing import ModelListResponseError
+
+
+def extract_vertex_model_page(payload: Any) -> tuple[frozenset[str], str | None]:
+    """Translate one Google publisher-model page to OpenAI-compatible model IDs."""
+    if not isinstance(payload, Mapping):
+        raise _malformed("expected an object")
+    models = payload.get("publisherModels")
+    if not _is_sequence(models):
+        raise _malformed("expected top-level publisherModels array")
+
+    model_ids: set[str] = set()
+    for item in models:
+        if not isinstance(item, Mapping):
+            raise _malformed("expected every publisherModels item to be an object")
+        name = item.get("name")
+        if not isinstance(name, str):
+            raise _malformed("expected every publisher model to include name")
+        model_ids.add(_openai_model_id(name))
+
+    next_page_token = payload.get("nextPageToken")
+    if next_page_token is not None and not isinstance(next_page_token, str):
+        raise _malformed("expected nextPageToken to be a string")
+    return frozenset(model_ids), next_page_token or None
+
+
+def _openai_model_id(resource_name: str) -> str:
+    parts = resource_name.split("/", 3)
+    if (
+        len(parts) != 4
+        or parts[0] != "publishers"
+        or not parts[1].strip()
+        or parts[2] != "models"
+        or not parts[3].strip()
+    ):
+        raise _malformed("expected publisher model resource names")
+    return f"{parts[1]}/{parts[3]}"
+
+
+def _is_sequence(value: Any) -> bool:
+    return isinstance(value, Sequence) and not isinstance(
+        value, str | bytes | bytearray
+    )
+
+
+def _malformed(reason: str) -> ModelListResponseError:
+    return ModelListResponseError(f"VERTEX model-list response is malformed: {reason}")

tests/api/test_admin.py

@@ -152,6 +152,15 @@ def test_admin_api_fetches_bypass_browser_cache():
     assert 'cache: "no-store"' in script
 
 
+def test_admin_provider_cards_support_non_key_configuration():
+    script = Path("src/free_claude_code/api/admin_static/admin.js").read_text(
+        encoding="utf-8"
+    )
+
+    assert '"missing_config"' in script
+    assert ": provider.configuration;" in script
+
+
 def test_admin_page_no_longer_renders_generated_env_panel(monkeypatch, tmp_path):
     _set_home(monkeypatch, tmp_path)
     app = create_test_app()

tests/config/test_config.py

@@ -39,6 +39,7 @@ class TestSettings:
 
         monkeypatch.delenv("CLAUDE_WORKSPACE", raising=False)
         monkeypatch.delenv("MODEL", raising=False)
+        monkeypatch.delenv("VERTEX_LOCATION", raising=False)
         monkeypatch.delenv("HTTP_READ_TIMEOUT", raising=False)
         monkeypatch.delenv("HTTP_CONNECT_TIMEOUT", raising=False)
         monkeypatch.setitem(Settings.model_config, "env_file", ())
@@ -58,6 +59,7 @@ class TestSettings:
         assert settings.debug_subagent_stack is False
         assert settings.log_level == "INFO"
         assert settings.open_admin_browser is True
+        assert settings.vertex_location == "global"
 
     def test_open_admin_browser_loads_from_environment(self, monkeypatch):
         from free_claude_code.config.settings import Settings
@@ -337,6 +339,18 @@ class TestSettings:
         assert settings.cloudflare_account_id == "cf-account"
         assert settings.cloudflare_proxy == "http://proxy.test:8080"
 
+    def test_vertex_settings_from_env(self, monkeypatch):
+        """Vertex project, location, and proxy env vars load into settings."""
+        from free_claude_code.config.settings import Settings
+
+        monkeypatch.setenv("VERTEX_PROJECT_ID", "vertex-project")
+        monkeypatch.setenv("VERTEX_LOCATION", "us-central1")
+        monkeypatch.setenv("VERTEX_PROXY", "http://proxy.test:8080")
+        settings = Settings()
+        assert settings.vertex_project_id == "vertex-project"
+        assert settings.vertex_location == "us-central1"
+        assert settings.vertex_proxy == "http://proxy.test:8080"
+
     def test_vercel_settings_from_env(self, monkeypatch):
         """Vercel AI Gateway key and proxy env vars load into settings."""
         from free_claude_code.config.settings import Settings

tests/config/test_provider_catalog.py

@@ -42,3 +42,18 @@ def test_ollama_cloud_is_remote_and_distinct_from_local_ollama() -> None:
     assert cloud.credential_env == "OLLAMA_API_KEY"
     assert local.local is True
     assert local.credential_env is None
+
+
+def test_provider_configuration_attrs_cover_multi_field_and_adc_providers() -> None:
+    assert PROVIDER_CATALOG["cloudflare"].configuration_attrs() == (
+        "cloudflare_api_token",
+        "cloudflare_account_id",
+    )
+    assert PROVIDER_CATALOG["vertex"].configuration_attrs() == ("vertex_project_id",)
+
+
+def test_every_provider_declares_its_configuration_boundary() -> None:
+    assert all(
+        descriptor.configuration_attrs() or descriptor.static_credential is not None
+        for descriptor in PROVIDER_CATALOG.values()
+    )

tests/contracts/test_admin_provider_manifest.py

@@ -117,3 +117,32 @@ def test_cloudflare_account_id_is_admin_provider_field() -> None:
     assert entry.settings_attr == "cloudflare_account_id"
     assert entry.section_id == "providers"
     assert entry.secret is False
+
+
+def test_vertex_project_and_location_are_admin_provider_fields() -> None:
+    project = FIELD_BY_KEY["VERTEX_PROJECT_ID"]
+    location = FIELD_BY_KEY["VERTEX_LOCATION"]
+
+    assert project.settings_attr == "vertex_project_id"
+    assert project.section_id == "providers"
+    assert project.secret is False
+    assert location.settings_attr == "vertex_location"
+    assert location.default == "global"
+
+
+def test_vertex_admin_status_uses_project_configuration_not_an_api_key() -> None:
+    from free_claude_code.config.admin.status import provider_config_status
+
+    def vertex_status(project_id: str) -> dict[str, object]:
+        statuses = provider_config_status(
+            {
+                "VERTEX_PROJECT_ID": {"value": project_id},
+                "VERTEX_LOCATION": {"value": "global"},
+            }
+        )
+        return next(status for status in statuses if status["provider_id"] == "vertex")
+
+    assert vertex_status("")["status"] == "missing_config"
+    assert vertex_status("")["label"] == "Missing configuration"
+    assert vertex_status("")["configuration"] == "VERTEX_PROJECT_ID"
+    assert vertex_status("vertex-project")["status"] == "configured"

tests/contracts/test_feature_manifest.py

@@ -16,6 +16,7 @@ from free_claude_code.providers.openai_chat import (
     OPENAI_CHAT_PROFILES,
     OpenAIChatProvider,
 )
+from free_claude_code.providers.vertex import VertexProvider
 from smoke.features import FEATURE_INVENTORY, README_FEATURES, feature_ids
 
 VALID_SOURCE = {"readme", "public_surface"}
@@ -98,6 +99,7 @@ def test_provider_and_platform_registries_include_advertised_builtins() -> None:
         "lmstudio": LMStudioProvider,
         "github_models": GitHubModelsProvider,
         "gemini": GeminiProvider,
+        "vertex": VertexProvider,
     }
     assert set(OPENAI_CHAT_PROFILES).isdisjoint(specialized_provider_classes)
     assert set(PROVIDER_CATALOG) == (

tests/contracts/test_provider_catalog_order.py

@@ -9,6 +9,7 @@ _EXPECTED_PROVIDER_ORDER: tuple[str, ...] = (
     "nvidia_nim",
     "open_router",
     "gemini",
+    "vertex",
     "deepseek",
     "mistral",
     "mistral_codestral",

tests/contracts/test_smoke_config.py

@@ -46,6 +46,8 @@ def _settings(**overrides):
         "github_models_token": "",
         "zai_api_key": "",
         "gemini_api_key": "",
+        "vertex_project_id": "",
+        "vertex_location": "global",
         "groq_api_key": "",
         "sambanova_api_key": "",
         "cerebras_api_key": "",
@@ -174,6 +176,23 @@ def test_bedrock_provider_configuration_uses_official_api_key(monkeypatch) -> No
     assert models[0].source == "provider_default"
 
 
+def test_vertex_provider_configuration_uses_project_id(monkeypatch) -> None:
+    monkeypatch.delenv("FCC_SMOKE_MODEL_VERTEX", raising=False)
+    config = _smoke_config(
+        settings=_settings(
+            model="ollama/llama3.1",
+            ollama_base_url="",
+            vertex_project_id="vertex-project",
+        )
+    )
+
+    assert config.has_provider_configuration("vertex")
+    models = config.provider_smoke_models()
+    assert [model.provider for model in models] == ["vertex"]
+    assert models[0].full_model == "vertex/google/gemini-3.5-flash"
+    assert models[0].source == "provider_default"
+
+
 def test_wafer_provider_configuration_uses_api_key(monkeypatch) -> None:
     monkeypatch.delenv("FCC_SMOKE_MODEL_WAFER", raising=False)
     config = _smoke_config(

tests/providers/test_gemini.py

@@ -7,8 +7,8 @@ import pytest
 from free_claude_code.config.provider_catalog import GEMINI_DEFAULT_BASE
 from free_claude_code.providers.base import ProviderConfig
 from free_claude_code.providers.gemini import GeminiProvider
-from free_claude_code.providers.gemini.quirks import (
-    GEMINI_SKIP_THOUGHT_SIGNATURE_VALIDATOR,
+from free_claude_code.providers.google_openai import (
+    GOOGLE_SKIP_THOUGHT_SIGNATURE_VALIDATOR,
 )
 from tests.providers.request_factory import make_messages_request
 from tests.providers.support import passthrough_rate_limiter, reasoning_for
@@ -291,7 +291,7 @@ def test_build_request_body_adds_current_turn_fallback_signature(
 
     tool_calls = body["messages"][1]["tool_calls"]
     assert tool_calls[0]["extra_content"] == {
-        "google": {"thought_signature": GEMINI_SKIP_THOUGHT_SIGNATURE_VALIDATOR}
+        "google": {"thought_signature": GOOGLE_SKIP_THOUGHT_SIGNATURE_VALIDATOR}
     }
     assert "extra_content" not in tool_calls[1]
 

tests/providers/test_model_validation.py

@@ -42,6 +42,7 @@ def _settings(
     wafer_api_key: str = "",
     opencode_api_key: str = "",
     zai_api_key: str = "",
+    vertex_project_id: str = "",
 ) -> Settings:
     return Settings.model_construct(
         model=model,
@@ -55,6 +56,7 @@ def _settings(
         wafer_api_key=wafer_api_key,
         opencode_api_key=opencode_api_key,
         zai_api_key=zai_api_key,
+        vertex_project_id=vertex_project_id,
         log_api_error_tracebacks=False,
     )
 
@@ -486,6 +488,28 @@ async def test_runtime_refresh_model_list_cache_uses_configured_remote_keys_and_
     assert result.failed_provider_ids == ()
 
 
+@pytest.mark.asyncio
+async def test_runtime_refresh_model_list_cache_treats_vertex_project_as_configuration() -> (
+    None
+):
+    settings = _settings(
+        model="nvidia_nim/nim-model",
+        vertex_project_id="vertex-project",
+    )
+    runtime = _manager(
+        settings,
+        {"vertex": FakeProvider(frozenset({"google/gemini-3.5-flash"}))},
+    )
+
+    result = await runtime.refresh_model_list_cache()
+
+    assert runtime.cached_model_ids() == {
+        "vertex": frozenset({"google/gemini-3.5-flash"})
+    }
+    assert result.refreshed_provider_ids == ("vertex",)
+    assert result.failed_provider_ids == ()
+
+
 @pytest.mark.asyncio
 async def test_runtime_refresh_model_list_cache_keeps_prior_cache_on_failure() -> None:
     settings = _settings(

tests/providers/test_provider_runtime.py

@@ -38,6 +38,7 @@ from free_claude_code.providers.runtime import (
     build_provider_config,
     create_provider,
 )
+from free_claude_code.providers.vertex import VertexProvider
 
 
 def _make_settings(**overrides):
@@ -93,6 +94,9 @@ def _make_settings(**overrides):
     mock.cloudflare_proxy = ""
     mock.gemini_api_key = ""
     mock.gemini_proxy = ""
+    mock.vertex_project_id = "test-vertex-project"
+    mock.vertex_location = "global"
+    mock.vertex_proxy = ""
     mock.groq_api_key = ""
     mock.groq_proxy = ""
     mock.cerebras_api_key = ""
@@ -389,6 +393,7 @@ def test_create_provider_uses_openai_chat_openrouter_by_default():
 def test_create_provider_instantiates_each_builtin():
     settings = _make_settings(
         gemini_api_key="test_gemini_key",
+        vertex_project_id="test-vertex-project",
         groq_api_key="test_groq_key",
         cerebras_api_key="test_cerebras_key",
         fireworks_api_key="test_fireworks_key",
@@ -431,6 +436,7 @@ def test_create_provider_instantiates_each_builtin():
         "github_models": GitHubModelsProvider,
         "zai": OpenAIChatProvider,
         "gemini": GeminiProvider,
+        "vertex": VertexProvider,
         "groq": OpenAIChatProvider,
         "sambanova": OpenAIChatProvider,
         "cerebras": OpenAIChatProvider,

tests/providers/test_vertex.py

@@ -0,0 +1,386 @@
+"""Tests for Google Vertex AI authentication, discovery, and Chat Completions."""
+
+import asyncio
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+from google.auth.credentials import Credentials
+from google.auth.exceptions import DefaultCredentialsError, TransportError
+from google.auth.transport.requests import Request
+
+from free_claude_code.application.errors import ApplicationUnavailableError
+from free_claude_code.config.provider_catalog import VERTEX_AI_API_ROOT
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+from free_claude_code.providers.base import ProviderConfig
+from free_claude_code.providers.model_listing import ModelListResponseError
+from free_claude_code.providers.vertex import VertexProvider
+from free_claude_code.providers.vertex.auth import GoogleAccessTokenProvider
+from free_claude_code.providers.vertex.endpoint import (
+    vertex_openai_base_url,
+    vertex_publisher_models_url,
+    vertex_service_endpoint,
+)
+from free_claude_code.providers.vertex.models import extract_vertex_model_page
+from tests.providers.request_factory import make_messages_request
+from tests.providers.support import passthrough_rate_limiter, reasoning_for
+
+_PROJECT_ID = "my-project"
+_GLOBAL_OPENAI_BASE = (
+    "https://aiplatform.googleapis.com/v1/projects/my-project/locations/global/"
+    "endpoints/openapi"
+)
+_GLOBAL_MODELS_URL = (
+    "https://aiplatform.googleapis.com/v1beta1/publishers/google/models"
+)
+
+
+class FakeCredentials(Credentials):
+    """Minimal mutable Google credentials for deterministic refresh tests."""
+
+    def __init__(
+        self,
+        *,
+        token: str | None = None,
+        expired: bool = True,
+        refresh_error: Exception | None = None,
+    ) -> None:
+        super().__init__()
+        self.token = token
+        self._expired = expired
+        self._refresh_error = refresh_error
+        self.refresh_count = 0
+        self.refresh_request: object | None = None
+
+    @property
+    def expired(self) -> bool:
+        return self._expired
+
+    def refresh(self, request: object) -> None:
+        self.refresh_request = request
+        self.refresh_count += 1
+        if self._refresh_error is not None:
+            raise self._refresh_error
+        self.token = "refreshed-token"
+        self._expired = False
+
+
+def _token_provider(
+    credentials: FakeCredentials | None = None,
+) -> GoogleAccessTokenProvider:
+    value = credentials or FakeCredentials(token="access-token", expired=False)
+
+    def loader() -> Credentials:
+        return value
+
+    return GoogleAccessTokenProvider(loader)
+
+
+def _provider(
+    *,
+    location: str = "global",
+    token_provider: GoogleAccessTokenProvider | None = None,
+) -> VertexProvider:
+    return VertexProvider(
+        ProviderConfig(api_key="", base_url=VERTEX_AI_API_ROOT),
+        project_id=_PROJECT_ID,
+        location=location,
+        rate_limiter=passthrough_rate_limiter(),
+        access_token_provider=token_provider or _token_provider(),
+    )
+
+
+@pytest.mark.parametrize(
+    ("location", "service_endpoint"),
+    [
+        ("global", "https://aiplatform.googleapis.com"),
+        ("us-central1", "https://us-central1-aiplatform.googleapis.com"),
+    ],
+)
+def test_vertex_endpoints_use_global_or_regional_hosts(
+    location: str, service_endpoint: str
+) -> None:
+    assert vertex_service_endpoint(location) == service_endpoint
+    assert vertex_openai_base_url("project/name", location) == (
+        f"{service_endpoint}/v1/projects/project%2Fname/locations/{location}/"
+        "endpoints/openapi"
+    )
+    assert vertex_publisher_models_url(location) == (
+        f"{service_endpoint}/v1beta1/publishers/google/models"
+    )
+
+
+@pytest.mark.parametrize("project_id", ["", "   "])
+def test_vertex_endpoint_requires_project_id(project_id: str) -> None:
+    with pytest.raises(ApplicationUnavailableError, match="VERTEX_PROJECT_ID"):
+        vertex_openai_base_url(project_id, "global")
+
+
+@pytest.mark.parametrize("location", ["", "US central1", "us/central1"])
+def test_vertex_endpoint_rejects_unsafe_locations(location: str) -> None:
+    with pytest.raises(ApplicationUnavailableError, match="VERTEX_LOCATION"):
+        vertex_service_endpoint(location)
+
+
+@pytest.mark.asyncio
+async def test_access_token_provider_reuses_valid_token_without_refresh() -> None:
+    credentials = FakeCredentials(token="cached-token", expired=False)
+    token_provider = _token_provider(credentials)
+
+    assert await token_provider() == "cached-token"
+    assert await token_provider() == "cached-token"
+    assert credentials.refresh_count == 0
+
+
+@pytest.mark.asyncio
+async def test_access_token_provider_coalesces_concurrent_refreshes() -> None:
+    credentials = FakeCredentials()
+    token_provider = _token_provider(credentials)
+
+    tokens = await asyncio.gather(*(token_provider() for _ in range(10)))
+
+    assert tokens == ["refreshed-token"] * 10
+    assert credentials.refresh_count == 1
+
+
+@pytest.mark.asyncio
+async def test_access_token_refresh_uses_the_vertex_proxy() -> None:
+    credentials = FakeCredentials()
+    token_provider = GoogleAccessTokenProvider(
+        lambda: credentials,
+        proxy="socks5://proxy.test:1080",
+    )
+
+    assert await token_provider() == "refreshed-token"
+    assert isinstance(credentials.refresh_request, Request)
+    session = credentials.refresh_request.session
+    assert session.proxies == {
+        "http": "socks5://proxy.test:1080",
+        "https": "socks5://proxy.test:1080",
+    }
+
+
+@pytest.mark.asyncio
+async def test_missing_adc_is_non_retryable_authentication_failure() -> None:
+    def missing_credentials() -> Credentials:
+        raise DefaultCredentialsError("sensitive local path")
+
+    token_provider = GoogleAccessTokenProvider(missing_credentials)
+
+    with pytest.raises(ExecutionFailure) as exc_info:
+        await token_provider()
+
+    failure = exc_info.value
+    assert failure.kind is FailureKind.AUTHENTICATION
+    assert failure.status_code == 401
+    assert failure.retryable is False
+    assert "gcloud auth application-default login" in failure.message
+    assert "sensitive local path" not in failure.message
+
+
+@pytest.mark.asyncio
+async def test_transient_adc_refresh_failure_is_retryable() -> None:
+    credentials = FakeCredentials(
+        refresh_error=TransportError("temporary auth service failure")
+    )
+    token_provider = _token_provider(credentials)
+
+    with pytest.raises(ExecutionFailure) as exc_info:
+        await token_provider()
+
+    failure = exc_info.value
+    assert failure.kind is FailureKind.UNAVAILABLE
+    assert failure.status_code == 503
+    assert failure.retryable is True
+    assert "temporary auth service failure" not in failure.message
+
+
+def test_vertex_provider_supplies_renewable_token_callback_to_openai() -> None:
+    token_provider = _token_provider()
+    with (
+        patch(
+            "free_claude_code.providers.openai_chat.provider.AsyncOpenAI"
+        ) as openai_client,
+        patch("free_claude_code.providers.vertex.client.httpx.AsyncClient"),
+    ):
+        provider = _provider(token_provider=token_provider)
+
+    assert provider._provider_name == "VERTEX"
+    assert provider._base_url == _GLOBAL_OPENAI_BASE
+    assert openai_client.call_args.kwargs["api_key"] is token_provider
+    assert openai_client.call_args.kwargs["default_headers"] == {
+        "x-goog-user-project": _PROJECT_ID
+    }
+
+
+def test_vertex_request_uses_google_thinking_budget_without_named_effort() -> None:
+    provider = _provider()
+    request = make_messages_request(
+        "google/gemini-3.5-flash",
+        thinking={"type": "enabled", "budget_tokens": 2048},
+    )
+
+    body = provider._build_request_body(request, reasoning=reasoning_for(request))
+
+    assert body["model"] == "google/gemini-3.5-flash"
+    assert "reasoning_effort" not in body
+    assert body["extra_body"]["extra_body"]["google"]["thinking_config"] == {
+        "include_thoughts": True,
+        "thinking_budget": 2048,
+    }
+
+
+def test_vertex_request_maps_reasoning_off_to_zero_budget() -> None:
+    provider = _provider()
+    request = make_messages_request(
+        "google/gemini-3.5-flash",
+        thinking={"type": "disabled"},
+    )
+
+    body = provider._build_request_body(request, reasoning=reasoning_for(request))
+
+    assert body["extra_body"]["extra_body"]["google"]["thinking_config"] == {
+        "thinking_budget": 0,
+        "include_thoughts": False,
+    }
+
+
+def test_vertex_model_page_translates_google_resource_names_generically() -> None:
+    model_ids, page_token = extract_vertex_model_page(
+        {
+            "publisherModels": [
+                {"name": "publishers/google/models/gemini-3.5-flash"},
+                {"name": "publishers/acme/models/custom-chat"},
+            ],
+            "nextPageToken": "next-page",
+        }
+    )
+
+    assert model_ids == frozenset({"google/gemini-3.5-flash", "acme/custom-chat"})
+    assert page_token == "next-page"
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [
+        None,
+        {},
+        {"publisherModels": "not-a-list"},
+        {"publisherModels": [{}]},
+        {"publisherModels": [{"name": "models/missing-publisher"}]},
+        {"publisherModels": [{"name": "publishers/google/models/   "}]},
+        {"publisherModels": [], "nextPageToken": 123},
+    ],
+)
+def test_vertex_model_page_rejects_malformed_responses(payload: object) -> None:
+    with pytest.raises(ModelListResponseError, match="VERTEX model-list response"):
+        extract_vertex_model_page(payload)
+
+
+@pytest.mark.asyncio
+async def test_vertex_model_discovery_follows_native_pagination() -> None:
+    provider = _provider()
+    responses = [
+        httpx.Response(
+            200,
+            json={
+                "publisherModels": [
+                    {"name": "publishers/google/models/gemini-3.5-flash"}
+                ],
+                "nextPageToken": "page-2",
+            },
+            request=httpx.Request("GET", _GLOBAL_MODELS_URL),
+        ),
+        httpx.Response(
+            200,
+            json={
+                "publisherModels": [{"name": "publishers/google/models/gemini-3.1-pro"}]
+            },
+            request=httpx.Request("GET", _GLOBAL_MODELS_URL),
+        ),
+    ]
+    with patch.object(
+        provider._model_list_client,
+        "get",
+        new_callable=AsyncMock,
+        side_effect=responses,
+    ) as get:
+        model_ids = await provider.list_model_ids()
+
+    assert model_ids == frozenset({"google/gemini-3.5-flash", "google/gemini-3.1-pro"})
+    assert get.await_args_list[0].kwargs == {
+        "params": None,
+        "headers": {
+            "Authorization": "Bearer access-token",
+            "x-goog-user-project": _PROJECT_ID,
+        },
+    }
+    assert get.await_args_list[1].kwargs == {
+        "params": {"pageToken": "page-2"},
+        "headers": {
+            "Authorization": "Bearer access-token",
+            "x-goog-user-project": _PROJECT_ID,
+        },
+    }
+    assert all(response.is_closed for response in responses)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "response",
+    [
+        httpx.Response(
+            200,
+            json={"publisherModels": []},
+            request=httpx.Request("GET", _GLOBAL_MODELS_URL),
+        ),
+        httpx.Response(
+            200,
+            content=b"not-json",
+            request=httpx.Request("GET", _GLOBAL_MODELS_URL),
+        ),
+    ],
+)
+async def test_vertex_model_discovery_rejects_unusable_success_response(
+    response: httpx.Response,
+) -> None:
+    provider = _provider()
+    with (
+        patch.object(
+            provider._model_list_client,
+            "get",
+            new_callable=AsyncMock,
+            return_value=response,
+        ),
+        pytest.raises(ModelListResponseError, match="VERTEX model-list response"),
+    ):
+        await provider.list_model_ids()
+
+    assert response.is_closed
+
+
+@pytest.mark.asyncio
+async def test_vertex_model_discovery_rejects_repeated_page_token() -> None:
+    provider = _provider()
+    responses = [
+        httpx.Response(
+            200,
+            json={"publisherModels": [], "nextPageToken": "same"},
+            request=httpx.Request("GET", _GLOBAL_MODELS_URL),
+        ),
+        httpx.Response(
+            200,
+            json={"publisherModels": [], "nextPageToken": "same"},
+            request=httpx.Request("GET", _GLOBAL_MODELS_URL),
+        ),
+    ]
+    with (
+        patch.object(
+            provider._model_list_client,
+            "get",
+            new_callable=AsyncMock,
+            side_effect=responses,
+        ),
+        pytest.raises(ModelListResponseError, match="repeated nextPageToken"),
+    ):
+        await provider.list_model_ids()

uv.lock

@@ -318,6 +318,56 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/0d/4a/331fe2caf6799d591109bb9c08083080f6de90a823695d412a935622abb2/coverage-7.13.4-py3-none-any.whl", hash = "sha256:1af1641e57cf7ba1bd67d677c9abdbcd6cc2ab7da3bca7fa1e2b7e50e65f2ad0", size = 211242, upload-time = "2026-02-09T12:59:02.032Z" },
 ]
 
+[[package]]
+name = "cryptography"
+version = "49.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cffi", marker = "platform_python_implementation != 'PyPy'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/1f/99/d1c90d6041656cc6ee229dc99cd67fd0cd5aec3c5f7d72fffc27cc750054/cryptography-49.0.0.tar.gz", hash = "sha256:f89660a348f4f78a92366240a61404e337586ef7f5909a2fef59ca88ef505493", size = 854345, upload-time = "2026-06-12T20:02:30.512Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9b/22/adf66990e63584a68dfb50c24f48a125c07b1699899381c8151e63ed458c/cryptography-49.0.0-cp311-abi3-macosx_11_0_arm64.whl", hash = "sha256:966fe0e9c67490071f14c0d2b1cb2dfb3023c5ce39457343931415f08382f2db", size = 4032100, upload-time = "2026-06-12T20:02:32.143Z" },
+    { url = "https://files.pythonhosted.org/packages/09/41/3797cfaf69cae04a13ee78ebd83f0678d9c02b4779d21ce24445326f1a69/cryptography-49.0.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:36d1709f992593689b45bda411498d62c6e365f2ca00b84657d4dadd24de16db", size = 4692978, upload-time = "2026-06-12T20:01:21.305Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/8b/43011f7ebe515a8aa20d61f290a326cd890c2e738e16e59eaff8d9c3a412/cryptography-49.0.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:0e959b578856a3924bc0cbb710fc12c387b9412a951389f3ca61704a9e25f325", size = 4716422, upload-time = "2026-06-12T20:01:48.566Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/91/01ce7303a4579e6d3a6abef01bd322848e9ea7a219adcabc5048b9033571/cryptography-49.0.0-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:53ecee2e23f7169b6117e99fc8a944e5e50f79e69758a83b52a00cb98ab2b2d2", size = 4700503, upload-time = "2026-06-12T20:02:47.091Z" },
+    { url = "https://files.pythonhosted.org/packages/62/99/a2c95cf8293f07491e9e27c20cc4dcd18176d944e674679adeb1d0173fd6/cryptography-49.0.0-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:2eda353d8a27bcbcaa4cbed18994a74ab4d19a2ca897db188ea269ab9b71419b", size = 5309779, upload-time = "2026-06-12T20:02:08.987Z" },
+    { url = "https://files.pythonhosted.org/packages/20/2c/0622f20ff02b2ef32558733443805dc82fd4c275be01b2d19d14676f3a1b/cryptography-49.0.0-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:2afe9051da7ae7bd5905da5a949280c7d2bb75682e188f650a9d0f2756b834c6", size = 4749683, upload-time = "2026-06-12T20:02:03.335Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/5b/c5246635d5fd3b64e0d45ae10e99fd32fe9676a79915ccfe5a61ba9af1a5/cryptography-49.0.0-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:0b82e28ee398a386f0807bba7884d30f25218855690f45115831bcce5d90822c", size = 4337874, upload-time = "2026-06-12T20:02:54.323Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/88/05563c7fe2e914e87d1a536d06fe83e66b4e1d95cb593e05aea375531da8/cryptography-49.0.0-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:ccac2bfebc306b862133e3bb71f3f6ee8bb525240089b2d952e4144b3a6d5da7", size = 4700283, upload-time = "2026-06-12T20:01:34.822Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/b6/d7696e4e890d6ae1469935164c9e5215c557671cb78d6e3f458ccceaa632/cryptography-49.0.0-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:d0527ce944105f257f605a827d6ebead966c752038b6e8656abb9c5edee6fc68", size = 5265844, upload-time = "2026-06-12T20:01:24.09Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/3c/f3ad17eecc1a57b0ba236dc01f90e783c51f4a2f35f64777cc4f47a184b2/cryptography-49.0.0-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:cbc77da8c523d5abd028635ba850a6966fcee2c82e2bf65a41d1d8afe0f98be9", size = 4749290, upload-time = "2026-06-12T20:01:30.848Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/01/339573cf1023163a400b0b5d16f6d507de413b9f60be6fd1b77feeaf6737/cryptography-49.0.0-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:b87e65d263b3e5d3bb92a57e2a6638e2f31110fa7aa890c7b2dbba42248d0a3f", size = 4834612, upload-time = "2026-06-12T20:01:29.246Z" },
+    { url = "https://files.pythonhosted.org/packages/71/fd/577302e213a1be9468f92d1afef66fcf1ef83d516819d9992ca547f592bd/cryptography-49.0.0-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:66ec79c3904820572d7e987abdf304281f141d37ad9a489b8e97066e7b9b6459", size = 4980804, upload-time = "2026-06-12T20:01:42.853Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/09/f42b1d190c5ba75f72062a387f8030d1d75f6ab035788f1d9c4b01de6525/cryptography-49.0.0-cp311-abi3-win_amd64.whl", hash = "sha256:e5dfc1e64de5677cec922ffa8da89c546d0415bf6efdf081842e5d44c84e1f0e", size = 3810026, upload-time = "2026-06-12T20:02:39.262Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/9e/db72b3ae7fc9cfad53e630e56c6ae83b9b6ff0bf3718ffb8012d20b3aabf/cryptography-49.0.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:73a205dce83953d131a4aa1e0fd917a2fd1c5b1eef251e9d7152efefcbf5caf7", size = 4013892, upload-time = "2026-06-12T20:02:10.735Z" },
+    { url = "https://files.pythonhosted.org/packages/86/12/c48a424f38db03027be9f7ed5c7dc5de9933dbee992865f98b13727a009d/cryptography-49.0.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:196ecd6a36e4e9aa10270393bb98d8df88fccee0bf1e5128b91ae4eb4375896d", size = 4678835, upload-time = "2026-06-12T20:02:48.743Z" },
+    { url = "https://files.pythonhosted.org/packages/68/28/8a3ad4653662c93fc44dc4e5d8fd374c25c42e07b34bbfbadf49cf57a5a8/cryptography-49.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7abcee80084cda3f7691f3eb1ce480d8df49cec637b429aa35986c1de71738aa", size = 4697239, upload-time = "2026-06-12T20:02:56.03Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/b2/2193fc74f81aee4f9b62733133b73b5176718932ed8f2e4b03fa040480a6/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:4ae387c9cb68ea569ca17e490d66d8142b81c3cc814bf179974b7d146e490bbb", size = 4685593, upload-time = "2026-06-12T20:02:50.666Z" },
+    { url = "https://files.pythonhosted.org/packages/47/f1/1d3eaa243bfc5de4a187b22aa8c048b3e4980bfbe830ac46e6bac2e66947/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:f37d847238971164fdbc68ade6f6574aecc9c0af714190e2083429ff68f4ce9d", size = 5289961, upload-time = "2026-06-12T20:01:46.468Z" },
+    { url = "https://files.pythonhosted.org/packages/58/39/2d51306721330c486495853eda1c567880ff036de15a14c4b74f399934af/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:c2bc30226390d60ea19d9f82b19db005fe0452154a23c1c410c12ea801e43561", size = 4731145, upload-time = "2026-06-12T20:02:16.832Z" },
+    { url = "https://files.pythonhosted.org/packages/17/50/983e838c7fd0d87fd8c969bcdd328edaf5f756e38df5281637424c155873/cryptography-49.0.0-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:07cab27cc7b7e0fd28e5e26bb9eeedde5c135c868b46de4a27845abe94af6122", size = 4321719, upload-time = "2026-06-12T20:02:52.611Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/f5/8f571d7e27c55bce9f76f026143bcb1e040a4233149ecca0bea5fa5dd5f7/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:b20133d204d2bb56ba047642199603876c872026ca53e79c35b83772ab2cc505", size = 4685209, upload-time = "2026-06-12T20:02:07.282Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/84/0e27016a6fc5a0886f797018b26aa42f40c09a82332bff77822a451deaaa/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:b970c6da94d5bb18629db453d14f2a1300f6bf59b61e9b82377931ef95504866", size = 5246285, upload-time = "2026-06-12T20:01:32.439Z" },
+    { url = "https://files.pythonhosted.org/packages/11/2d/5e1fb307cb5931881516b464c98774b3f2c36b5d4bb9a2830253cf553cad/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:d8ecde755e2e91bf773fc94e8c9d730cd7f2007004cb492263a794ec3899a1c8", size = 4730441, upload-time = "2026-06-12T20:02:01.469Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/c0/bff5a02ee731d207d6a1ed51732549d8c53d2bc8da1d10ec6f2844201d68/cryptography-49.0.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e3fb64c420688e5319ae25113a354015abbd8dffbfbc41781a1ea66fc7622ac3", size = 4815869, upload-time = "2026-06-12T20:01:36.574Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/26/814681d14248d95d73d5c3eea0c39a94eb8302df966f670a2c60de90974b/cryptography-49.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:32703d93296f5c1f4b53349ad3a250c2cae0fdecd3a3dd5d47e616d8d616af27", size = 4960948, upload-time = "2026-06-12T20:02:18.688Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/fe/93ecac273d3738939d023612ad12cca9a3740a5345d69fda04134c43fd96/cryptography-49.0.0-cp314-cp314t-win_amd64.whl", hash = "sha256:33cd0565932807baddb67b96dbee92f2c374b5c89dee09fd74079aeb8c8dba61", size = 3799153, upload-time = "2026-06-12T20:01:39.059Z" },
+    { url = "https://files.pythonhosted.org/packages/19/2a/5bb823f5bedcf80718cea7fbc95ec5515cca3769633c4b01a32be7f30e7c/cryptography-49.0.0-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:ec5e529fb80935c94fe7b729f9972b50e351a0e6b50aa294fd5cabb109fcc29a", size = 4025947, upload-time = "2026-06-12T20:01:25.745Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/df/40577043ca124e17012f408ddddaeb213b856336ac82ddb3bc915f39e29f/cryptography-49.0.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:f78ff2c9ed8dc2d036b0f4d640e22522213d047c1b14e61205a7e55c80a494d4", size = 4692429, upload-time = "2026-06-12T20:01:53.628Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/99/2d13299eb3dd27b02dcfaafcc91d6b5cb3329f7cbd6d8f51921acd566c1a/cryptography-49.0.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:35b151772baff2c74cba7fa290ceaff4c3b11c0c881eb93eb5dbc05a7cfbba18", size = 4700968, upload-time = "2026-06-12T20:02:45.383Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/4d/9c0cd02f95e2602dd5e563da149ee0830abef3537be8b34dc56281ebe27a/cryptography-49.0.0-cp39-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:0f21641cf4b30fca7aee061ced0ec7ad7b073518088b7c9969a297c0ae796c69", size = 4697758, upload-time = "2026-06-12T20:01:41.13Z" },
+    { url = "https://files.pythonhosted.org/packages/24/01/186c825898477d77e2324d5360fefe622ff1d8d1963ec0554e2cada8ec77/cryptography-49.0.0-cp39-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:9e82dcc8e56052715fb18b2429e3bca4823b1629136a2084fc45a9a5cecb9b64", size = 5298863, upload-time = "2026-06-12T20:02:24.579Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/7b/62cbbab75d0659865bf0273790031544a0b16c8072d258f9428dcd8190dc/cryptography-49.0.0-cp39-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:6f2debedf9ca60cf1d5bd466475638af5130f89965605cd818484d19987d3a21", size = 4735983, upload-time = "2026-06-12T20:01:50.14Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/72/3e798c064bc39e471008075d0f9bc9daf77a80879c092e4a8e170c585ed4/cryptography-49.0.0-cp39-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:8c25ceb16df5b9435f3f6a9829204985b0e0cbee3b48aacd432c7d2c850b44d9", size = 4334173, upload-time = "2026-06-12T20:01:44.743Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/ee/6fca21d1ac73e06f8bef71940abfd4d2f6472b4bca284d770f32bd4086f6/cryptography-49.0.0-cp39-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:28d8b15e6275f12c8a207dc309dfa957903c927d08d0cc937ee3f63f200693cc", size = 4697298, upload-time = "2026-06-12T20:02:20.918Z" },
+    { url = "https://files.pythonhosted.org/packages/67/d0/a5fcd3515f0bae49a7b6d0413cc1bdccdcc1fc0047037a0d480642cdc5d6/cryptography-49.0.0-cp39-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:6fc361c34fb6aac015ce19435876635e5c6d21db31998b0920f675f131e043b8", size = 5254338, upload-time = "2026-06-12T20:02:22.737Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/84/84fe36f19caf857d61cb7fc9c63035a47ffabd84ea12d1d393148efa3615/cryptography-49.0.0-cp39-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:2400ef9c9e2299a25614eb1dea3db54a69b1349efd043bfac9c67630d136df36", size = 4735650, upload-time = "2026-06-12T20:02:41.389Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/a0/db537264e234f7273a73ec020873d6d6b39dfd8a53db78b550ca8320440e/cryptography-49.0.0-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:67e1d20ad9ef3a563c59ef22e7a8a0b8210bd26604369ea4a30a7c66aefe504e", size = 4834820, upload-time = "2026-06-12T20:01:51.847Z" },
+    { url = "https://files.pythonhosted.org/packages/93/77/8df9eb486495979bccecd1062e2eaf435250e84437040295b57d09048b0b/cryptography-49.0.0-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:42b0684e0e40cf26122427802486f6d93aea593612603a94fbf260c7eb1e9c1b", size = 4967968, upload-time = "2026-06-12T20:02:12.524Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/e6/f60198ea8d9dfa15fff9ed4ca02ce362f6eadd9ba757dcc50634c4257b63/cryptography-49.0.0-cp39-abi3-win_amd64.whl", hash = "sha256:026ac7423e6fa66872d3bf889be5974507da3944f866f704fa200eadacd00001", size = 3785547, upload-time = "2026-06-12T20:02:26.847Z" },
+]
+
 [[package]]
 name = "cuda-bindings"
 version = "13.0.3"
@@ -570,12 +620,13 @@ wheels = [
 
 [[package]]
 name = "free-claude-code"
-version = "4.10.0"
+version = "4.11.0"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },
     { name = "discord-py" },
     { name = "fastapi", extra = ["standard"] },
+    { name = "google-auth", extra = ["requests"] },
     { name = "httpx", extra = ["socks"] },
     { name = "jsonschema" },
     { name = "loguru" },
@@ -585,6 +636,7 @@ dependencies = [
     { name = "pydantic-settings" },
     { name = "python-dotenv" },
     { name = "python-telegram-bot" },
+    { name = "requests", extra = ["socks"] },
     { name = "tiktoken" },
     { name = "uvicorn" },
 ]
@@ -618,6 +670,7 @@ requires-dist = [
     { name = "aiohttp", specifier = ">=3.14.1" },
     { name = "discord-py", specifier = ">=2.7.1" },
     { name = "fastapi", extras = ["standard"], specifier = ">=0.139.2" },
+    { name = "google-auth", extras = ["requests"], specifier = ">=2.40.0" },
     { name = "grpcio", marker = "extra == 'voice'", specifier = ">=1.82.1" },
     { name = "grpcio-tools", marker = "extra == 'voice'", specifier = ">=1.81.1" },
     { name = "httpx", extras = ["socks"], specifier = ">=0.28.1" },
@@ -631,6 +684,7 @@ requires-dist = [
     { name = "pydantic-settings", specifier = ">=2.14.2" },
     { name = "python-dotenv", specifier = ">=1.2.2" },
     { name = "python-telegram-bot", specifier = ">=22.8" },
+    { name = "requests", extras = ["socks"], specifier = ">=2.32.0" },
     { name = "tiktoken", specifier = ">=0.13.0" },
     { name = "torch", marker = "extra == 'voice-local'", specifier = ">=2.13.0", index = "https://download.pytorch.org/whl/cu130" },
     { name = "transformers", marker = "extra == 'voice-local'", specifier = ">=5.14.1" },
@@ -698,6 +752,24 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e6/ab/fb21f4c939bb440104cc2b396d3be1d9b7a9fd3c6c2a53d98c45b3d7c954/fsspec-2026.2.0-py3-none-any.whl", hash = "sha256:98de475b5cb3bd66bedd5c4679e87b4fdfe1a3bf4d707b151b3c07e58c9a2437", size = 202505, upload-time = "2026-02-05T21:50:51.819Z" },
 ]
 
+[[package]]
+name = "google-auth"
+version = "2.56.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cryptography" },
+    { name = "pyasn1-modules" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/58/66/b4ba60005743e01933e22b4f62313e063f7460458b7d8a358427b4930013/google_auth-2.56.0.tar.gz", hash = "sha256:f90fa030b569a92654b9d690665a073841df33d57487be53db583a9a0867a553", size = 364629, upload-time = "2026-07-13T19:09:57.143Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a8/7d/cd3e187f14ce832e419e70709bfcc40cb0dc11517d5d03c9d3919bcc3101/google_auth-2.56.0-py3-none-any.whl", hash = "sha256:6e88c10217e07a92bfd01cac8ee99e32ccfb08414c3102e6c5b8d58f37a0d1e0", size = 257976, upload-time = "2026-07-13T19:09:42.685Z" },
+]
+
+[package.optional-dependencies]
+requests = [
+    { name = "requests" },
+]
+
 [[package]]
 name = "grpcio"
 version = "1.82.1"
@@ -1500,6 +1572,27 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/8c/c7/7bb2e321574b10df20cbde462a94e2b71d05f9bbda251ef27d104668306a/psutil-7.2.2-cp37-abi3-win_arm64.whl", hash = "sha256:8c233660f575a5a89e6d4cb65d9f938126312bca76d8fe087b947b3a1aaac9ee", size = 134617, upload-time = "2026-01-28T18:15:36.514Z" },
 ]
 
+[[package]]
+name = "pyasn1"
+version = "0.6.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a4/9a/23310166d960def5897e91fe20e5b724601b02a22e84ba1f94232c0b7f67/pyasn1-0.6.4.tar.gz", hash = "sha256:9c447d8431c947fe4c8febc4ed9e760bc29011a5b01e5c74b67025bd9fb8ce81", size = 151262, upload-time = "2026-07-09T01:12:33.988Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9a/3b/6163796d69c3977d1e4287bea4a6979161cbbdd170ebb430511e8e1999ce/pyasn1-0.6.4-py3-none-any.whl", hash = "sha256:deda9277cfd454080ec40b207fb6df82206a3a2688735233cdcd8d3d565f088b", size = 84410, upload-time = "2026-07-09T01:12:32.92Z" },
+]
+
+[[package]]
+name = "pyasn1-modules"
+version = "0.4.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pyasn1" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e9/e6/78ebbb10a8c8e4b61a59249394a4a594c1a7af95593dc933a349c8d00964/pyasn1_modules-0.4.2.tar.gz", hash = "sha256:677091de870a80aae844b1ca6134f54652fa2c8c5a52aa396440ac3106e941e6", size = 307892, upload-time = "2025-03-28T02:41:22.17Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/47/8d/d529b5d697919ba8c11ad626e835d4039be708a35b0d22de83a269a6682c/pyasn1_modules-0.4.2-py3-none-any.whl", hash = "sha256:29253a9207ce32b64c3ac6600edc75368f98473906e8fd1043bd6b5b1de2c14a", size = 181259, upload-time = "2025-03-28T02:41:19.028Z" },
+]
+
 [[package]]
 name = "pycparser"
 version = "3.0"
@@ -1606,6 +1699,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" },
 ]
 
+[[package]]
+name = "pysocks"
+version = "1.7.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/bd/11/293dd436aea955d45fc4e8a35b6ae7270f5b8e00b53cf6c024c83b657a11/PySocks-1.7.1.tar.gz", hash = "sha256:3f8804571ebe159c380ac6de37643bb4685970655d3bba243530d6558b799aa0", size = 284429, upload-time = "2019-09-20T02:07:35.714Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8d/59/b4572118e098ac8e46e399a1dd0f2d85403ce8bbaad9ec79373ed6badaf9/PySocks-1.7.1-py3-none-any.whl", hash = "sha256:2725bd0a9925919b9b51739eea5f9e2bae91e83288108a9ad338b2e3a4435ee5", size = 16725, upload-time = "2019-09-20T02:06:22.938Z" },
+]
+
 [[package]]
 name = "pytest"
 version = "9.1.1"
@@ -1786,6 +1888,11 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl", hash = "sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6", size = 64738, upload-time = "2025-08-18T20:46:00.542Z" },
 ]
 
+[package.optional-dependencies]
+socks = [
+    { name = "pysocks" },
+]
+
 [[package]]
 name = "rich"
 version = "14.3.2"