Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

feat: Vertex AI runs on Application Default Credentials; Express is deleted

Jack Rudenkoae785275889f
diff --git a/AI_AGENT_GUIDE.md b/AI_AGENT_GUIDE.md
index 5f81b6e3..1d681564 100644
--- a/AI_AGENT_GUIDE.md
+++ b/AI_AGENT_GUIDE.md
@@ -107,10 +107,9 @@ claudish --model vertex/openai/gpt-oss-120b-maas "reason"
# OR Gemini direct
export GEMINI_API_KEY='...'
- # OR Vertex AI (Express mode)
- export VERTEX_API_KEY='...'
-
- # OR Vertex AI (OAuth mode - uses gcloud ADC)
+ # OR Vertex AI (Application Default Credentials)
+ gcloud auth application-default login
+ # Optional - claudish otherwise uses the ADC quota project or `gcloud config get project`
export VERTEX_PROJECT='your-gcp-project-id'
```
diff --git a/README.md b/README.md
index 636ac24b..bd896246 100644
--- a/README.md
+++ b/README.md
@@ -367,8 +367,7 @@ Claudish automatically loads `.env` from the current directory at startup. For t
| `OPENCODE_GO_API_KEY` | OpenCode Zen Go plan (`zgo@`) | _(separate from the metered Zen credential)_ |
| `LITELLM_API_KEY` | LiteLLM (`ll@`) — requires `LITELLM_BASE_URL` | |
| `POE_API_KEY` | Poe (`poe@`) | |
-| `VERTEX_API_KEY` | Vertex AI Express (`v@`) | |
-| `VERTEX_PROJECT` | Vertex AI OAuth mode (`v@`) | `GOOGLE_CLOUD_PROJECT` |
+| `VERTEX_PROJECT` | Vertex AI (`v@`) — optional; the ADC quota project or `gcloud config get project` is used otherwise | `GOOGLE_CLOUD_PROJECT` |
| `ANTHROPIC_API_KEY` | Placeholder (suppresses Claude Code dialog) | |
#### Bundled Endpoint Catalog
@@ -645,7 +644,7 @@ claudish --model [email protected]:3 "code review" # 3 concurrent requests
| `oc@` | OllamaCloud | `OLLAMA_API_KEY` | `[email protected]` |
| `zen@` | OpenCode Zen | `OPENCODE_API_KEY` | `zen@gpt-5-nano` |
| `zgo@`, `zengo@` | OpenCode Zen Go plan | `OPENCODE_GO_API_KEY` | `zgo@glm-5` |
-| `v@`, `vertex@` | Vertex AI | `VERTEX_API_KEY` | `[email protected]` |
+| `v@`, `vertex@` | Vertex AI | _(Application Default Credentials; `VERTEX_PROJECT` optional)_ | `[email protected]` |
| `ag@`, `antigravity@` | Antigravity (Gemini subscription) | _(OAuth via `claudish login antigravity`)_ | `[email protected]` |
| `go@` | _deprecated alias → `ag@`_ | _(OAuth)_ | `[email protected]` |
| `poe@` | Poe | `POE_API_KEY` | `poe@GPT-4o` |
@@ -691,9 +690,10 @@ claudish --model openrouter@deepseek/deepseek-r1 "deep analysis"
claudish --model [email protected] "code review"
claudish --model [email protected] "analyze image"
-# Vertex AI - Google Cloud
-VERTEX_API_KEY=... claudish --model [email protected] "task"
-VERTEX_PROJECT=my-project claudish --model [email protected] "OAuth mode"
+# Vertex AI - Google Cloud (Application Default Credentials)
+gcloud auth application-default login # once
+claudish --model [email protected] "task" # project from ADC / gcloud config
+VERTEX_PROJECT=my-project claudish --model [email protected] "explicit project"
# Alibaba Cloud Model Studio products
claudish --model [email protected] "implement feature"
diff --git a/docs/api-key-architecture.md b/docs/api-key-architecture.md
index 2f34fd31..e964a389 100644
--- a/docs/api-key-architecture.md
+++ b/docs/api-key-architecture.md
@@ -33,7 +33,7 @@ When a model ID is provided, it's resolved in this order:
| `g/`, `gemini/` | Google Gemini | `GEMINI_API_KEY` | Direct Gemini API |
| `ag/`, `antigravity/` | Antigravity (Gemini subscription) | OAuth | Requires `claudish login antigravity` |
| `go/` | _deprecated alias → `ag/`_ | OAuth | Gemini Code Assist was retired by Google |
-| `v/`, `vertex/` | Vertex AI | `VERTEX_API_KEY` or `VERTEX_PROJECT` (OAuth) | Google Cloud |
+| `v/`, `vertex/` | Vertex AI | Application Default Credentials (`VERTEX_PROJECT` optional) | Google Cloud |
| `oai/` | OpenAI | `OPENAI_API_KEY` | Direct OpenAI API |
| `mmax/`, `mm/` | MiniMax | `MINIMAX_API_KEY` | Anthropic-compatible |
| `kimi/`, `moonshot/` | Kimi/Moonshot | `MOONSHOT_API_KEY` or `KIMI_API_KEY` | Anthropic-compatible |
diff --git a/docs/settings-reference.md b/docs/settings-reference.md
index 1c594988..4cef214d 100644
--- a/docs/settings-reference.md
+++ b/docs/settings-reference.md
@@ -212,15 +212,22 @@ Claudish automatically loads `.env` from the current working directory at startu
| `XAI_API_KEY` | xAI / Grok (direct API, detected in model selector) | | https://x.ai/ |
| `LITELLM_API_KEY` | LiteLLM proxy (`ll@`, `litellm@`) | | https://docs.litellm.ai/ |
| `POE_API_KEY` | Poe (`poe@`) | | https://poe.com/ |
-| `VERTEX_API_KEY` | Vertex AI Express mode (`v@`, `vertex@`) | | https://console.cloud.google.com/vertex-ai |
-| `VERTEX_PROJECT` | Vertex AI OAuth mode — GCP project ID | `GOOGLE_CLOUD_PROJECT` | GCP Console |
+| `VERTEX_PROJECT` | Vertex AI (`v@`, `vertex@`) — GCP project ID; optional, see the note below | `GOOGLE_CLOUD_PROJECT` | GCP Console |
| `VERTEX_LOCATION` | Vertex AI region | `us-central1` | |
| `GOOGLE_APPLICATION_CREDENTIALS` | Path to GCP service account JSON file (Vertex OAuth) | | GCP Console |
| `GOOGLE_CLOUD_PROJECT` | GCP project ID (Vertex AI) | `GOOGLE_CLOUD_PROJECT_ID` | |
-**Note on Vertex AI**: Vertex supports two authentication modes:
-- Express mode (`VERTEX_API_KEY`): Uses the Gemini API endpoint; supports Gemini models only.
-- OAuth mode (`VERTEX_PROJECT` + Application Default Credentials via `gcloud auth application-default login` or `GOOGLE_APPLICATION_CREDENTIALS`): Supports all Vertex models including partner models (Anthropic Claude, Mistral, etc.).
+**Note on Vertex AI (changed 2026-09-21)**: Vertex has ONE authentication mode — OAuth over a Google Cloud project, using Application Default Credentials (`gcloud auth application-default login`) or a service account (`GOOGLE_APPLICATION_CREDENTIALS`). It reaches every Vertex model, partner models (Anthropic Claude, Mistral, etc.) included.
+
+The Express API-key mode (`VERTEX_API_KEY`) is **removed**, not deprecated: the variable is no longer read anywhere. Express served Gemini models from the plain Gemini API endpoint, which `GEMINI_API_KEY` and `g@` already do.
+
+You do not have to set `VERTEX_PROJECT`. Claudish resolves the project in this order, and stops at the first answer:
+
+1. `VERTEX_PROJECT`, then `GOOGLE_CLOUD_PROJECT`
+2. `quota_project_id` in `~/.config/gcloud/application_default_credentials.json`
+3. `gcloud config get project`
+
+If none of them answers, the error says so and names both remedies (`VERTEX_PROJECT=…` or `gcloud config set project …`). The project is resolved once per process and never written to disk, so `gcloud config set project` takes effect on the next run. `VERTEX_LOCATION` defaults to `us-central1`.
**Note on OpenCode Zen (changed 2026-08-22)**: `OPENCODE_API_KEY` is now **required** for every model on the zen endpoint. Claudish previously sent `"Bearer public"` when no key was set, on the basis that free-tier models (cost.input === 0) needed no credential. The endpoint answers `401 — Missing API key` to that token, and because the fallback also made the provider report **Ready** without ever issuing a request, the failure only surfaced under a live test. The fallback has been removed; a Zen row with no key now correctly reads "not set".
@@ -442,7 +449,7 @@ Provider part is **case-insensitive**. Shortcuts are resolved to canonical provi
| `oc`, `llama`, `lc`, `meta` | `ollamacloud` | OllamaCloud hosted API (`OLLAMA_API_KEY`) |
| `zen` | `opencode-zen` | OpenCode Zen (`OPENCODE_API_KEY` required) |
| `zengo`, `zgo` | `opencode-zen-go` | OpenCode Zen Go subscription plan (`OPENCODE_GO_API_KEY` required) |
-| `v`, `vertex` | `vertex` | Vertex AI (`VERTEX_API_KEY` or `VERTEX_PROJECT`) |
+| `v`, `vertex` | `vertex` | Vertex AI — Application Default Credentials (`VERTEX_PROJECT` optional) |
| `mistral` | `mistralai` | Direct Mistral API (`MISTRAL_API_KEY`) |
| `ag`, `antigravity` | `antigravity` | Gemini via your Antigravity subscription (`claudish login antigravity`) |
| `go` | `antigravity` | _deprecated alias_ — Gemini Code Assist was retired by Google |
diff --git a/packages/cli/AI_AGENT_GUIDE.md b/packages/cli/AI_AGENT_GUIDE.md
index 6b612101..0f566d68 100644
--- a/packages/cli/AI_AGENT_GUIDE.md
+++ b/packages/cli/AI_AGENT_GUIDE.md
@@ -92,10 +92,9 @@ Custom endpoints can be registered in `~/.claudish/config.json`. See [docs/setti
# OR Gemini direct
export GEMINI_API_KEY='...'
- # OR Vertex AI (Express mode)
- export VERTEX_API_KEY='...'
-
- # OR Vertex AI (OAuth mode - uses gcloud ADC)
+ # OR Vertex AI (Application Default Credentials)
+ gcloud auth application-default login
+ # Optional - claudish otherwise uses the ADC quota project or `gcloud config get project`
export VERTEX_PROJECT='your-gcp-project-id'
```
diff --git a/packages/cli/src/auth/credentials/vertex-credential.ts b/packages/cli/src/auth/credentials/vertex-credential.ts
index d664356c..9441d8b2 100644
--- a/packages/cli/src/auth/credentials/vertex-credential.ts
+++ b/packages/cli/src/auth/credentials/vertex-credential.ts
@@ -1,31 +1,42 @@
/**
* Vertex AI credential — ADC / service-account based (no interactive login).
*
- * Availability mirrors the existing vertex profile (provider-profiles.ts):
- * a Vertex project is configured (VERTEX_PROJECT / GOOGLE_CLOUD_PROJECT), or
- * VERTEX_API_KEY selects Express mode in the absence of a project. The request
- * token is obtained from the shared VertexAuthManager (gcloud ADC or service
- * account); there is no login/logout because auth is ADC-based.
+ * Availability mirrors the vertex profile (provider-profiles.ts): a Google Cloud
+ * project resolves (VERTEX_PROJECT / GOOGLE_CLOUD_PROJECT, the ADC file's
+ * quota_project_id, or `gcloud config get project`). The request token comes
+ * from the shared VertexAuthManager (gcloud ADC or service account); there is no
+ * login/logout because auth is ADC-based.
+ *
+ * There is no API-key mode. VERTEX_API_KEY (Express) was deleted on 2026-09-21.
*/
-import { getVertexAuthManager, selectVertexAuthMode } from "../vertex-auth.js";
+import {
+ getVertexAuthManager,
+ resolveVertexConfig,
+ selectVertexAuthMode,
+ validateVertexOAuthConfig,
+} from "../vertex-auth.js";
import type { CredentialProvider, RequestAuth, RequestAuthContext } from "./types.js";
export class VertexCredentialProvider implements CredentialProvider {
readonly catalogName = "vertex";
async isAvailable(): Promise<boolean> {
- return selectVertexAuthMode() !== null;
+ const config = await resolveVertexConfig();
+ return selectVertexAuthMode({ project: config?.projectId }) !== null;
}
async getRequestAuth(_ctx: RequestAuthContext): Promise<RequestAuth> {
- // A project selects OAuth even when an Express key is also configured.
- if (selectVertexAuthMode() === "project") {
+ const config = await resolveVertexConfig();
+ if (selectVertexAuthMode({ project: config?.projectId }) === "project") {
const token = await getVertexAuthManager().getAccessToken();
return { headers: { Authorization: `Bearer ${token}` } };
}
- const expressKey = process.env.VERTEX_API_KEY;
- if (expressKey) return { headers: { Authorization: `Bearer ${expressKey}` } };
- throw new Error("Vertex requires a configured project or Express key");
+ // Name the remedy rather than the symptom: with ADC present this is a
+ // missing PROJECT, and "no credential" would send the user to re-run a
+ // login that already succeeded.
+ throw new Error(
+ (await validateVertexOAuthConfig()) ?? "Vertex requires a Google Cloud project"
+ );
}
}
diff --git a/packages/cli/src/auth/oauth-registry.ts b/packages/cli/src/auth/oauth-registry.ts
index 38a1432e..4b673675 100644
--- a/packages/cli/src/auth/oauth-registry.ts
+++ b/packages/cli/src/auth/oauth-registry.ts
@@ -21,7 +21,7 @@ interface OAuthProviderDescriptor {
* - ollamacloud (OLLAMA_API_KEY) - API key only
* - z-ai (ZAI_API_KEY) - API key only
* - litellm (LITELLM_API_KEY) - API key only
- * - vertex (VERTEX_API_KEY / VERTEX_PROJECT) - uses ADC / service account
+ * - vertex (VERTEX_PROJECT, or the ADC / gcloud project) - uses ADC / service account
*
* These providers are covered by the direct API-key step (Step 3) in the
* auto-routing priority chain. OAuth entries can be added here in future
diff --git a/packages/cli/src/auth/vertex-auth-mode.test.ts b/packages/cli/src/auth/vertex-auth-mode.test.ts
index 5727dac9..5130bab2 100644
--- a/packages/cli/src/auth/vertex-auth-mode.test.ts
+++ b/packages/cli/src/auth/vertex-auth-mode.test.ts
@@ -1,18 +1,80 @@
-import { describe, expect, test } from "bun:test";
-import { selectVertexAuthMode } from "./vertex-auth.js";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+ resetVertexProjectDiscovery,
+ resolveVertexConfig,
+ selectVertexAuthMode,
+} from "./vertex-auth.js";
+
+const ENV_KEYS = ["VERTEX_PROJECT", "VERTEX_LOCATION", "GOOGLE_CLOUD_PROJECT"] as const;
+let originalEnv: Partial<Record<(typeof ENV_KEYS)[number], string>>;
+
+beforeEach(() => {
+ originalEnv = {};
+ for (const key of ENV_KEYS) {
+ originalEnv[key] = process.env[key];
+ delete process.env[key];
+ }
+ resetVertexProjectDiscovery();
+});
+
+afterEach(() => {
+ for (const key of ENV_KEYS) {
+ const value = originalEnv[key];
+ if (value === undefined) {
+ delete process.env[key];
+ } else {
+ process.env[key] = value;
+ }
+ }
+ resetVertexProjectDiscovery();
+});
describe("Vertex account selection", () => {
- test("a selected project takes precedence over an Express key", () => {
- expect(selectVertexAuthMode({ project: "chosen-project", expressKey: "configured-key" })).toBe(
- "project"
- );
+ test("a selected project uses project authentication", () => {
+ expect(selectVertexAuthMode({ project: "chosen-project" })).toBe("project");
});
- test("the Express key is selected only without a project", () => {
- expect(selectVertexAuthMode({ expressKey: "configured-key" })).toBe("express");
- });
+ // The Express API-key path was removed; there is no alternate auth mode to restore here.
test("neither mode is available without configuration", () => {
expect(selectVertexAuthMode({})).toBeNull();
});
});
+
+describe("Vertex project and location resolution", () => {
+ test("VERTEX_PROJECT and VERTEX_LOCATION take precedence", async () => {
+ process.env.VERTEX_PROJECT = "vertex-project";
+ process.env.VERTEX_LOCATION = "australia-southeast1";
+ process.env.GOOGLE_CLOUD_PROJECT = "lower-precedence-project";
+
+ await expect(resolveVertexConfig()).resolves.toEqual({
+ projectId: "vertex-project",
+ location: "australia-southeast1",
+ });
+ });
+
+ test("defaults the location when VERTEX_LOCATION is absent", async () => {
+ process.env.VERTEX_PROJECT = "vertex-project";
+
+ await expect(resolveVertexConfig()).resolves.toEqual({
+ projectId: "vertex-project",
+ location: "us-central1",
+ });
+ });
+
+ test("a reset keeps sequential environment changes isolated", async () => {
+ process.env.VERTEX_PROJECT = "first-project";
+ await expect(resolveVertexConfig()).resolves.toEqual({
+ projectId: "first-project",
+ location: "us-central1",
+ });
+
+ resetVertexProjectDiscovery();
+ process.env.VERTEX_PROJECT = "second-project";
+
+ await expect(resolveVertexConfig()).resolves.toEqual({
+ projectId: "second-project",
+ location: "us-central1",
+ });
+ });
+});
diff --git a/packages/cli/src/auth/vertex-auth.ts b/packages/cli/src/auth/vertex-auth.ts
index 847b069a..67c2a80c 100644
--- a/packages/cli/src/auth/vertex-auth.ts
+++ b/packages/cli/src/auth/vertex-auth.ts
@@ -8,10 +8,16 @@
*
* Used for partner models (Anthropic Claude, Mistral, etc.) and
* project-based Vertex AI access.
+ *
+ * OAuth over a project is the ONLY mode. The Express API-key path
+ * (VERTEX_API_KEY) was removed on 2026-09-21: ADC is Google's documented way
+ * into Vertex AI, and the second mode duplicated the Gemini direct API while
+ * making every caller branch on which one was active.
*/
import { exec } from "node:child_process";
import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
import { homedir } from "node:os";
import { join } from "node:path";
import { promisify } from "node:util";
@@ -19,6 +25,20 @@ import { log } from "../logger.js";
const execAsync = promisify(exec);
+/**
+ * The ADC file `gcloud auth application-default login` writes.
+ *
+ * One helper rather than the string in three places: the token path, the
+ * credential-presence check and the project resolution all read the SAME file,
+ * and a copy that drifted would make one of them disagree with the others.
+ */
+function adcCredentialsPath(): string {
+ return join(homedir(), ".config/gcloud/application_default_credentials.json");
+}
+
+/** Vertex location used when VERTEX_LOCATION is unset — a DEFAULT, never a guess. */
+const DEFAULT_VERTEX_LOCATION = "us-central1";
+
interface VertexAccessToken {
token: string;
expiresAt: number;
@@ -117,7 +137,7 @@ export class VertexAuthManager {
private async tryADC(): Promise<VertexAccessToken | null> {
try {
// Check if ADC credentials file exists
- const adcPath = join(homedir(), ".config/gcloud/application_default_credentials.json");
+ const adcPath = adcCredentialsPath();
if (!existsSync(adcPath)) {
log("[VertexAuth] ADC credentials file not found");
@@ -185,58 +205,181 @@ export class VertexAuthManager {
}
/**
- * Get Vertex AI configuration from environment
+ * Per-process memo of the DISCOVERED project — the ADC file's `quota_project_id`
+ * and `gcloud config`, i.e. the two tiers that cost I/O.
+ *
+ * The env tier is deliberately NOT memoized: `resolveVertexConfig` reads
+ * `VERTEX_PROJECT` fresh on every call, so a caller that sets it still wins
+ * immediately and no earlier discovery result can shadow it.
+ *
+ * Nothing here is written to disk. A resolved project is a fact about this
+ * machine's CURRENT gcloud state; a cached copy would outlive
+ * `gcloud config set project` and silently bill the previous project.
*/
-export function getVertexConfig(): VertexConfig | null {
- const projectId = process.env.VERTEX_PROJECT || process.env.GOOGLE_CLOUD_PROJECT;
+let discoveredProjectPromise: Promise<string | null> | null = null;
+
+/**
+ * Reset the discovery memo. Test seam — production resolves once per process.
+ */
+export function resetVertexProjectDiscovery(): void {
+ discoveredProjectPromise = null;
+}
+
+/** `quota_project_id` from the ADC file — the same file the token path reads. */
+async function readAdcQuotaProject(): Promise<string | null> {
+ try {
+ const raw = await readFile(adcCredentialsPath(), "utf-8");
+ const parsed = JSON.parse(raw) as { quota_project_id?: unknown };
+ const project =
+ typeof parsed.quota_project_id === "string" ? parsed.quota_project_id.trim() : "";
+ return project || null;
+ } catch (e: any) {
+ log(`[VertexAuth] No project in ADC file: ${e.message}`);
+ return null;
+ }
+}
+
+/**
+ * The project from `gcloud config`.
+ *
+ * `gcloud config get project` is the modern form; `gcloud config get-value
+ * project` is the older one and still the only one some installed CLIs accept,
+ * so the modern form is tried first and the older one ONLY after it errors — an
+ * old CLI rejects `get` outright, which is what distinguishes the two.
+ * Both print `(unset)` when nothing is configured — that is an ANSWER ("no
+ * project"), not a value, so it ends the search rather than being returned.
+ *
+ * Same 10s timeout as the token calls above: a hung gcloud must not hang a
+ * request.
+ */
+async function readGcloudConfigProject(): Promise<string | null> {
+ for (const command of ["gcloud config get project", "gcloud config get-value project"]) {
+ try {
+ const { stdout } = await execAsync(command, { timeout: 10000 });
+ // gcloud prints the value on stdout and its notices on stderr, but older
+ // versions also echo "Your active configuration is: [default]" — take the
+ // last non-empty line rather than the whole buffer.
+ const value =
+ stdout
+ .split("\n")
+ .map((line) => line.trim())
+ .filter((line) => line.length > 0)
+ .pop() ?? "";
+ // A command that RAN and said "(unset)" has answered: there is no
+ // configured project. Trying the other spelling would ask a working CLI
+ // the same question twice, on the exact path (ADC but no project) where
+ // the user is waiting for an error message.
+ if (!value || value === "(unset)" || /\s/.test(value)) return null;
+ log(`[VertexAuth] Project from \`${command}\``);
+ return value;
+ } catch (e: any) {
+ log(`[VertexAuth] \`${command}\` failed: ${e.message}`);
+ }
+ }
+ return null;
+}
+
+/**
+ * Discovery, at most ONCE per process.
+ *
+ * Both outcomes are memoized, the null included: a machine with no gcloud
+ * project would otherwise pay two `gcloud` invocations (up to their 10s timeout)
+ * on every single request.
+ */
+function discoverOnce(): Promise<string | null> {
+ if (!discoveredProjectPromise) {
+ discoveredProjectPromise = discoverVertexProject();
+ }
+ return discoveredProjectPromise;
+}
+
+/** Discovery tiers only — the env tier lives in resolveVertexConfig. */
+async function discoverVertexProject(): Promise<string | null> {
+ const fromAdc = await readAdcQuotaProject();
+ if (fromAdc) {
+ log("[VertexAuth] Project from ADC quota_project_id");
+ return fromAdc;
+ }
+ return readGcloudConfigProject();
+}
+
+/**
+ * Resolve the Vertex project and location.
+ *
+ * Precedence, highest first:
+ * 1. VERTEX_PROJECT / GOOGLE_CLOUD_PROJECT (VERTEX_LOCATION for the location)
+ * 2. `quota_project_id` in ~/.config/gcloud/application_default_credentials.json
+ * 3. `gcloud config get project`
+ *
+ * Tiers 2 and 3 exist because ADC users have ALREADY told gcloud which project
+ * they are on; making them repeat it in a claudish-specific variable is how
+ * `vertex@` ended up unreachable for anyone who had set up Google's own way in.
+ *
+ * Returns null when no project can be resolved — never a placeholder, never an
+ * invented id. `validateVertexOAuthConfig` turns that null into the remedy.
+ */
+export async function resolveVertexConfig(): Promise<VertexConfig | null> {
+ const projectId =
+ process.env.VERTEX_PROJECT || process.env.GOOGLE_CLOUD_PROJECT || (await discoverOnce());
if (!projectId) {
return null;
}
return {
projectId,
- location: process.env.VERTEX_LOCATION || "us-central1",
+ location: process.env.VERTEX_LOCATION || DEFAULT_VERTEX_LOCATION,
};
}
-/** A configured project selects OAuth; Express applies only without a project. */
-export function selectVertexAuthMode(
- configured: { project?: string; expressKey?: string } = {
- project: getVertexConfig()?.projectId,
- expressKey: process.env.VERTEX_API_KEY,
- }
-): "project" | "express" | null {
- if (configured.project) return "project";
- return configured.expressKey ? "express" : null;
+/**
+ * Vertex has exactly ONE way in: a Google Cloud project plus OAuth from ADC or a
+ * service account. The Express API-key path was DELETED (2026-09-21) — Google's
+ * documented route into Vertex AI is ADC, and a second mode meant every caller
+ * carried a branch for a path this project does not support.
+ *
+ * Pure and synchronous on purpose: the caller resolves the project with
+ * `resolveVertexConfig` (async — it may read the ADC file or run gcloud) and
+ * hands the answer in, so there is no hidden env read here that could disagree
+ * with the resolution the rest of the request uses.
+ */
+export function selectVertexAuthMode(configured: { project?: string }): "project" | null {
+ return configured.project ? "project" : null;
}
/**
- * Validate Vertex AI OAuth configuration
- * Returns error message if invalid, null if OK
+ * Validate Vertex AI OAuth configuration.
+ * Returns an error message if unusable, null if OK.
*/
-export function validateVertexOAuthConfig(): string | null {
- const config = getVertexConfig();
+export async function validateVertexOAuthConfig(): Promise<string | null> {
+ const hasADC = existsSync(adcCredentialsPath());
+ const hasServiceAccount = !!process.env.GOOGLE_APPLICATION_CREDENTIALS;
+ const noCredentials =
+ "No Vertex AI credentials found.\n\n" +
+ "Options:\n" +
+ "1. Run: gcloud auth application-default login\n" +
+ "2. Set: export GOOGLE_APPLICATION_CREDENTIALS='/path/to/service-account.json'";
+
+ const config = await resolveVertexConfig();
if (!config) {
+ // Credentials but no project is a DIFFERENT failure from no credentials, and
+ // naming the wrong one sends the user to re-run a login that already worked.
+ if (!hasADC && !hasServiceAccount) return noCredentials;
+ const credentialKind = hasADC
+ ? "Application Default Credentials are"
+ : "A service account credential is";
return (
- "Missing VERTEX_PROJECT environment variable.\n\n" +
- "Set it with:\n" +
+ `${credentialKind} present, but no Google Cloud project is set.\n\n` +
+ "Set one with either:\n" +
" export VERTEX_PROJECT='your-gcp-project-id'\n" +
- " export VERTEX_LOCATION='us-central1' # optional"
+ " gcloud config set project your-gcp-project-id\n\n" +
+ "Claudish also reads quota_project_id from the ADC file and `gcloud config get project`, " +
+ "so either of the above is enough — no claudish-specific configuration is needed.\n" +
+ `Location defaults to ${DEFAULT_VERTEX_LOCATION}; override it with VERTEX_LOCATION.`
);
}
- // Check for credentials
- const adcPath = join(homedir(), ".config/gcloud/application_default_credentials.json");
- const hasADC = existsSync(adcPath);
- const hasServiceAccount = !!process.env.GOOGLE_APPLICATION_CREDENTIALS;
-
if (!hasADC && !hasServiceAccount) {
- return (
- "No Vertex AI credentials found.\n\n" +
- "Options:\n" +
- "1. Run: gcloud auth application-default login\n" +
- "2. Set: export GOOGLE_APPLICATION_CREDENTIALS='/path/to/service-account.json'"
- );
+ return noCredentials;
}
return null;
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 6ab059e6..c3b759d1 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -2459,8 +2459,7 @@ ${h("ENVIRONMENT VARIABLES")}
${blue("OPENCODE_GO_API_KEY")} OpenCode Zen Go plan ${dim("(zgo@, zengo@; separate plan key)")}
${blue("POE_API_KEY")} Poe ${dim("(poe@)")}
${blue("LITELLM_API_KEY")} LiteLLM ${dim("(litellm@, ll@; needs LITELLM_BASE_URL)")}
- ${blue("VERTEX_API_KEY")} Vertex AI Express ${dim("(v@)")}
- ${blue("VERTEX_PROJECT")} Vertex AI project ID ${dim("(OAuth mode, v@)")}
+ ${blue("VERTEX_PROJECT")} Vertex AI project ID ${dim("(v@; optional — ADC quota project or `gcloud config get project` is used otherwise)")}
${blue("VERTEX_LOCATION")} Vertex AI region ${dim("(default: us-central1)")}
${blue("ANTHROPIC_API_KEY")} Placeholder (prevents Claude Code dialog)
${blue("ANTHROPIC_AUTH_TOKEN")} Placeholder (prevents Claude Code login screen)
diff --git a/packages/cli/src/providers/api-key-map.ts b/packages/cli/src/providers/api-key-map.ts
index 59c59ae6..e9bc2a36 100644
--- a/packages/cli/src/providers/api-key-map.ts
+++ b/packages/cli/src/providers/api-key-map.ts
@@ -51,6 +51,10 @@ export const API_KEY_MAP: Record<string, { envVar: string; aliases?: string[] }>
// refuses to sign with — a row asserting readiness nothing has verified, the
// same defect as the removed publicKeyFallback.
"opencode-zen-go": { envVar: "OPENCODE_GO_API_KEY" },
- vertex: { envVar: "VERTEX_API_KEY", aliases: ["VERTEX_PROJECT"] },
+ // Vertex takes no API key: the project ID plus Application Default
+ // Credentials. VERTEX_API_KEY (Express) was deleted on 2026-09-21, and it was
+ // the primary here — so `--probe` asked for a variable no longer read while
+ // treating the one that IS read as an alias.
+ vertex: { envVar: "VERTEX_PROJECT" },
poe: { envVar: "POE_API_KEY" },
};
diff --git a/packages/cli/src/providers/provider-definitions.ts b/packages/cli/src/providers/provider-definitions.ts
index 96bfe977..48525517 100644
--- a/packages/cli/src/providers/provider-definitions.ts
+++ b/packages/cli/src/providers/provider-definitions.ts
@@ -18,7 +18,7 @@ import type { ModelDiscoveryDescriptor } from "./model-discovery.js";
// Type-only, like ModelDiscoveryDescriptor below: erased at compile time, so
// declaring the handler here costs nothing at module load. The 28 heavy imports
// in provider-profiles.ts arrive only when `lazyHandler`'s thunk is invoked.
-import type { ProfileContext, ProviderProfile } from "./provider-profiles.js";
+import type { AsyncProviderProfile, ProfileContext, ProviderProfile } from "./provider-profiles.js";
import { getRuntimeProviders } from "./runtime-providers.js";
// ---------------------------------------------------------------------------
@@ -101,7 +101,9 @@ type ProfileBuilders = typeof import("./provider-profiles.js");
* be a third place to typo a provider name, which is the exact failure this
* merge exists to remove.
*/
-function lazyHandler(pick: (m: ProfileBuilders) => ProviderProfile): LazyHandlerFactory {
+function lazyHandler(
+ pick: (m: ProfileBuilders) => ProviderProfile | AsyncProviderProfile
+): LazyHandlerFactory {
return async (ctx) => pick(await import("./provider-profiles.js")).createHandler(ctx);
}
@@ -130,6 +132,25 @@ export interface ProviderDefinition {
baseUrl: string;
/** Environment variables that can override the base URL */
baseUrlEnvVars?: string[];
+ /**
+ * This provider's TRANSPORT builds the request URL itself, so an empty
+ * `baseUrl` is correct and complete rather than missing.
+ *
+ * Declared because "no base URL" otherwise means "not configured", and
+ * `getRemoteProviders()` drops such a provider from the registry — after which
+ * `resolveRemoteProvider("vertex@…")` returns null and the failure reads as a
+ * missing credential, sending the user to find a key that was never the
+ * problem. LiteLLM has the same empty `baseUrl` but a DIFFERENT cause: its URL
+ * arrives from `LITELLM_BASE_URL`, so resolving `baseUrlEnvVars` rescues it.
+ * No env var can ever rescue this case, because there is no single URL to
+ * name: Vertex's endpoint is assembled per request from the project, the
+ * location and the publisher
+ * (`https://<location>-aiplatform.googleapis.com/v1/projects/<project>/…`).
+ *
+ * A capability, not a name check: anything whose transport composes its own
+ * endpoint sets this, and nothing in the registry mentions "vertex".
+ */
+ buildsOwnEndpoint?: true;
/** API path template (e.g., "/v1/chat/completions") */
apiPath: string;
/** Primary API key environment variable */
@@ -874,10 +895,20 @@ export const BUILTIN_PROVIDERS: ProviderDefinition[] = [
displayName: "Vertex AI",
transport: "vertex",
baseUrl: "",
+ // The transport composes the endpoint from project + location + publisher,
+ // so the empty baseUrl above is the finished answer. Without this the
+ // registry filter drops Vertex entirely (see `buildsOwnEndpoint`).
+ buildsOwnEndpoint: true,
apiPath: "",
+ // Not an API key: the project ID, paired with Application Default
+ // Credentials. It stays on `apiKeyEnvVar` because that is what makes the
+ // credential authority resolve Vertex at all, and what names the remedy in
+ // "no credential" messages. VERTEX_API_KEY (Express) was REMOVED from
+ // `apiKeyAliases` on 2026-09-21 along with the mode itself. Claudish also
+ // resolves the project from the ADC file and `gcloud config` — see
+ // `resolveVertexConfig` — so an unset VERTEX_PROJECT is not fatal.
apiKeyEnvVar: "VERTEX_PROJECT",
- apiKeyAliases: ["VERTEX_API_KEY"],
- apiKeyDescription: "Vertex AI API Key",
+ apiKeyDescription: "Vertex AI project ID (with Application Default Credentials)",
apiKeyUrl: "https://console.cloud.google.com/vertex-ai",
shortcuts: ["v", "vertex"],
shortestPrefix: "v",
@@ -886,7 +917,7 @@ export const BUILTIN_PROVIDERS: ProviderDefinition[] = [
{ prefix: "vertex/", stripPrefix: true },
],
isDirectApi: true,
- description: "Vertex AI Express (v@, vertex@)",
+ description: "Vertex AI on Application Default Credentials (v@, vertex@)",
},
// ── LiteLLM ────────────────────────────────────────────────────────
diff --git a/packages/cli/src/providers/provider-profiles.ts b/packages/cli/src/providers/provider-profiles.ts
index 0112335c..21a39529 100644
--- a/packages/cli/src/providers/provider-profiles.ts
+++ b/packages/cli/src/providers/provider-profiles.ts
@@ -28,7 +28,7 @@ import { lookupModelEndpoint } from "../adapters/model-catalog.js";
import { OllamaAPIFormat } from "../adapters/ollama-api-format.js";
import { OpenAIAPIFormat } from "../adapters/openai-api-format.js";
import {
- getVertexConfig,
+ resolveVertexConfig,
selectVertexAuthMode,
validateVertexOAuthConfig,
} from "../auth/vertex-auth.js";
@@ -37,7 +37,6 @@ import type { ModelHandler } from "../handlers/types.js";
import { log, logStderr } from "../logger.js";
import { formatProvenanceLog, resolveApiKeyProvenance } from "./api-key-provenance.js";
import { getProviderByName } from "./provider-definitions.js";
-import { getRegisteredRemoteProviders } from "./remote-provider-registry.js";
import { getRuntimeProfiles } from "./runtime-providers.js";
import { AnthropicProviderTransport } from "./transport/anthropic-compat.js";
import { AntigravityProviderTransport } from "./transport/antigravity.js";
@@ -112,6 +111,23 @@ export interface ProviderProfile {
createHandler(ctx: ProfileContext): ModelHandler | null;
}
+/**
+ * A profile whose construction needs I/O before it can build anything.
+ *
+ * Only Vertex needs this: its endpoint is built from a project that may have to
+ * be read out of the ADC file or `gcloud config`. Kept as a SEPARATE type rather
+ * than widening `ProviderProfile.createHandler` to a union, because a union
+ * return type would force every existing caller of a sync profile to disambiguate
+ * a Promise it will never receive.
+ *
+ * `LazyHandlerFactory` (provider-definitions.ts) already returns a Promise, so a
+ * definition wires this exactly like a sync profile and nothing downstream
+ * changes.
+ */
+export interface AsyncProviderProfile {
+ createHandler(ctx: ProfileContext): Promise<ModelHandler | null>;
+}
+
// ---------------------------------------------------------------------------
// Profile implementations
// ---------------------------------------------------------------------------
@@ -466,70 +482,57 @@ export const litellmProfile: ProviderProfile = {
};
/**
- * Vertex AI — supports two modes:
- * 1. OAuth Mode (VERTEX_PROJECT) — full project-based access with OAuth tokens.
- * Uses VertexProviderTransport + publisher-specific format (Gemini/Anthropic/Default).
- * 2. Express Mode (VERTEX_API_KEY) — used when no project is configured.
- * Uses GeminiProviderTransport (with the gemini provider config) + GeminiAPIFormat.
+ * Vertex AI — ONE mode: OAuth over a Google Cloud project.
+ *
+ * Uses VertexProviderTransport + a publisher-specific format
+ * (Gemini/Anthropic/Default). The project comes from `resolveVertexConfig`
+ * (VERTEX_PROJECT, the ADC file's quota_project_id, or `gcloud config`), and the
+ * token from the credential authority via the transport.
+ *
+ * The Express API-key mode (VERTEX_API_KEY on the plain Gemini endpoint) was
+ * deleted on 2026-09-21. Returns null when no project resolves or no ADC /
+ * service-account credential is present, having logged which of the two it was.
*
- * Returns null if neither key nor project config is available.
+ * ASYNC because project resolution is: it may read the ADC file or shell out to
+ * gcloud. That is why this is an AsyncProviderProfile rather than a
+ * ProviderProfile — the sync contract every other provider meets cannot express
+ * an I/O-backed endpoint.
*/
-export const vertexProfile: ProviderProfile = {
- createHandler(ctx) {
- const mode = selectVertexAuthMode();
- const vertexConfig = getVertexConfig();
-
- if (mode === "project" && vertexConfig) {
- const oauthError = validateVertexOAuthConfig();
- if (oauthError) {
- log(`[Proxy] Vertex OAuth config error: ${oauthError}`);
- return null;
- }
- const parsed = parseVertexModel(ctx.modelName);
- const transport = new VertexProviderTransport(vertexConfig, parsed);
-
- let adapter: BaseModelAdapter;
- if (parsed.publisher === "google") {
- adapter = new GeminiAPIFormat(ctx.modelName);
- } else if (parsed.publisher === "anthropic") {
- adapter = new AnthropicAPIFormat(parsed.model, "vertex");
- } else {
- const modelId =
- parsed.publisher === "mistralai" ? parsed.model : `${parsed.publisher}/${parsed.model}`;
- adapter = new DefaultAPIFormat(modelId);
- }
-
- const handler = new ComposedHandler(transport, ctx.targetModel, ctx.modelName, ctx.port, {
- adapter,
- ...ctx.sharedOpts,
- });
- log(
- `[Proxy] Created Vertex AI OAuth handler (composed): ${ctx.modelName} [${parsed.publisher}] (project: ${vertexConfig.projectId})`
- );
- return handler;
+export const vertexProfile: AsyncProviderProfile = {
+ async createHandler(ctx) {
+ const configError = await validateVertexOAuthConfig();
+ const vertexConfig = await resolveVertexConfig();
+ if (
+ configError ||
+ !vertexConfig ||
+ selectVertexAuthMode({ project: vertexConfig.projectId }) !== "project"
+ ) {
+ log(`[Proxy] Vertex AI is not usable: ${configError ?? "no Google Cloud project resolved"}`);
+ return null;
}
- if (mode === "express") {
- // Express Mode — Vertex Express uses the standard Gemini API endpoint
- // but with VERTEX_API_KEY instead of GEMINI_API_KEY.
- // Must use the Gemini provider config (which has the correct baseUrl/apiPath)
- // because the vertex provider config has empty baseUrl/apiPath (designed for OAuth mode).
- const geminiConfig = getRegisteredRemoteProviders().find((p) => p.name === "gemini");
- const expressProvider = geminiConfig || ctx.provider;
- // ctx.apiKey is the authority-resolved Vertex credential (Express key when
- // VERTEX_API_KEY is set) — single source of truth, no raw env read here.
- const transport = new GeminiProviderTransport(expressProvider, ctx.modelName, ctx.apiKey);
- const adapter = new GeminiAPIFormat(ctx.modelName);
- const handler = new ComposedHandler(transport, ctx.targetModel, ctx.modelName, ctx.port, {
- adapter,
- ...ctx.sharedOpts,
- });
- log(`[Proxy] Created Vertex AI Express handler (composed): ${ctx.modelName}`);
- return handler;
+ const parsed = parseVertexModel(ctx.modelName);
+ const transport = new VertexProviderTransport(vertexConfig, parsed);
+
+ let adapter: BaseModelAdapter;
+ if (parsed.publisher === "google") {
+ adapter = new GeminiAPIFormat(ctx.modelName);
+ } else if (parsed.publisher === "anthropic") {
+ adapter = new AnthropicAPIFormat(parsed.model, "vertex");
+ } else {
+ const modelId =
+ parsed.publisher === "mistralai" ? parsed.model : `${parsed.publisher}/${parsed.model}`;
+ adapter = new DefaultAPIFormat(modelId);
}
- log("[Proxy] Vertex AI requires either VERTEX_API_KEY or VERTEX_PROJECT");
- return null;
+ const handler = new ComposedHandler(transport, ctx.targetModel, ctx.modelName, ctx.port, {
+ adapter,
+ ...ctx.sharedOpts,
+ });
+ log(
+ `[Proxy] Created Vertex AI OAuth handler (composed): ${ctx.modelName} [${parsed.publisher}] (project: ${vertexConfig.projectId})`
+ );
+ return handler;
},
};
diff --git a/packages/cli/src/providers/remote-provider-registry.test.ts b/packages/cli/src/providers/remote-provider-registry.test.ts
new file mode 100644
index 00000000..6ebe983c
--- /dev/null
+++ b/packages/cli/src/providers/remote-provider-registry.test.ts
@@ -0,0 +1,12 @@
+import { describe, expect, test } from "bun:test";
+import { resolveRemoteProvider } from "./remote-provider-registry.js";
+
+describe("remote provider registry", () => {
+ test("keeps a provider that builds its own endpoint despite an empty base URL", () => {
+ const resolved = resolveRemoteProvider("[email protected]");
+
+ expect(resolved).not.toBeNull();
+ expect(resolved?.provider.name).toBe("vertex");
+ expect(resolved?.modelName).toBe("gemini-2.5-flash");
+ });
+});
diff --git a/packages/cli/src/providers/remote-provider-registry.ts b/packages/cli/src/providers/remote-provider-registry.ts
index 4c9d4531..fad57ec0 100644
--- a/packages/cli/src/providers/remote-provider-registry.ts
+++ b/packages/cli/src/providers/remote-provider-registry.ts
@@ -41,11 +41,19 @@ const getRemoteProviders = (): RemoteProvider[] => {
.filter(
(def) =>
!def.isLocal &&
- // Resolve baseUrlEnvVars so user-deployed providers like LiteLLM
- // (static baseUrl: "", populated via LITELLM_BASE_URL) aren't filtered
- // out. Without this, resolveRemoteProvider("litellm@...") returns null
- // and probe-discovery / runtime routing both fail.
- getEffectiveBaseUrl(def) !== "" &&
+ // A provider needs SOMEWHERE to send the request. Two shapes satisfy
+ // that without a static baseUrl:
+ //
+ // 1. Resolve baseUrlEnvVars, so user-deployed providers like LiteLLM
+ // (static baseUrl: "", populated via LITELLM_BASE_URL) aren't
+ // filtered out. Without this, resolveRemoteProvider("litellm@...")
+ // returns null and probe-discovery / runtime routing both fail.
+ // 2. `buildsOwnEndpoint`, where the TRANSPORT assembles the URL per
+ // request — Vertex, from project + location + publisher. No env var
+ // can ever fill that in, so case 1 cannot cover it, and being
+ // dropped here made `vertex@…` unreachable while reporting itself as
+ // a missing credential.
+ (getEffectiveBaseUrl(def) !== "" || def.buildsOwnEndpoint === true) &&
def.name !== "qwen" &&
def.name !== "native-anthropic"
)
diff --git a/packages/cli/src/providers/transport/probe-discovery-modalities.test.ts b/packages/cli/src/providers/transport/probe-discovery-modalities.test.ts
new file mode 100644
index 00000000..3c0ee6bf
--- /dev/null
+++ b/packages/cli/src/providers/transport/probe-discovery-modalities.test.ts
@@ -0,0 +1,187 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type DiskCacheV3, type SlimModelEntry, writeAllModelsCache } from "../all-models-cache.js";
+import { _clearChatCapabilityIndex, classifyChatCapability } from "./probe-discovery.js";
+
+const CATALOG_GENERATION_ID = "g-20260920154425586-418ad3dd";
+
+// Trimmed verbatim from the live cloud models catalog generation above. Only
+// fields read by classifyChatCapability, plus aliases under test, are retained.
+const liveRows: SlimModelEntry[] = [
+ {
+ modelId: "gpt-5-image",
+ aliases: ["openai/gpt-5-image"],
+ outputModalities: ["image", "text"],
+ videoOutput: false,
+ },
+ {
+ modelId: "gemini-3.1-flash-image",
+ aliases: ["google/gemini-3.1-flash-image", "google/flash-image-3.1"],
+ outputModalities: ["image", "text"],
+ videoOutput: false,
+ },
+ {
+ modelId: "nano-banana-pro",
+ aliases: [],
+ outputModalities: ["image"],
+ supportsVision: true,
+ },
+ {
+ modelId: "qwen-audio-3.0-realtime-plus",
+ aliases: [],
+ outputModalities: ["audio", "text"],
+ videoOutput: false,
+ supportsTools: true,
+ },
+ {
+ modelId: "gpt-image-2.5-flare",
+ aliases: ["openai/gpt-image-2.5-flare"],
+ outputModalities: ["image"],
+ },
+ {
+ modelId: "gemini-omni-1.1-flash",
+ aliases: ["google/gemini-omni-1.1-flash"],
+ outputModalities: ["video"],
+ videoOutput: true,
+ },
+ {
+ modelId: "qwen-audio-3.0-tts-flash",
+ aliases: ["qwen/qwen-audio-3.0-tts-flash"],
+ outputModalities: ["audio"],
+ },
+ {
+ modelId: "gemini-embedding-2",
+ aliases: ["google/gemini-embedding-2", "google/gemini-embedding-2:batch"],
+ outputModalities: ["embeddings"],
+ },
+ {
+ modelId: "mai-transcribe-2",
+ aliases: ["microsoft/mai-transcribe-2", "MAI-Transcribe-2"],
+ outputModalities: ["transcription"],
+ },
+ {
+ modelId: "mai-voice-2",
+ aliases: ["microsoft/mai-voice-2", "MAI-Voice-2"],
+ outputModalities: ["speech"],
+ },
+ {
+ modelId: "llama-nemotron-rerank-vl-1b-v2",
+ aliases: ["nvidia/llama-nemotron-rerank-vl-1b-v2:free"],
+ outputModalities: ["rerank"],
+ },
+ {
+ modelId: "jev-1.13",
+ aliases: ["typesafe/jev-1.13", "~typesafe/jev-latest", "jev-1.13-free"],
+ outputModalities: ["decisions"],
+ },
+];
+
+// Contract-only rows. Generation g-20260920154425586-418ad3dd has no null or
+// empty output list and no videoOutput:true row that also publishes text. The
+// agreed precedence is recorded in
+// ai-docs/sessions/dev-feature-catalog-phase1-20260921-0015/implementation/modalities.md.
+const contractRows: SlimModelEntry[] = [
+ {
+ modelId: "contract-null-output-with-tools",
+ aliases: [],
+ outputModalities: null,
+ supportsTools: true,
+ },
+ {
+ modelId: "contract-empty-output-with-thinking",
+ aliases: [],
+ outputModalities: [],
+ supportsThinking: true,
+ },
+ {
+ modelId: "contract-video-output-with-text",
+ aliases: [],
+ outputModalities: ["text"],
+ videoOutput: true,
+ },
+];
+
+let tempDir = "";
+let cachePath = "";
+
+beforeEach(() => {
+ _clearChatCapabilityIndex();
+ tempDir = mkdtempSync(join(tmpdir(), "claudish-output-modalities-"));
+ cachePath = join(tempDir, "cloud-models-catalog-v3.json");
+ const cache: DiskCacheV3 = {
+ version: 3,
+ lastUpdated: "2026-09-20T15:44:25.586Z",
+ catalogGenerationId: CATALOG_GENERATION_ID,
+ entries: [...liveRows, ...contractRows],
+ models: [],
+ plans: [],
+ };
+ writeAllModelsCache(cache, cachePath);
+});
+
+afterEach(() => {
+ _clearChatCapabilityIndex();
+ rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("chat capability from output modalities", () => {
+ test("catalog text output outranks an image-generator name", () => {
+ expect(classifyChatCapability("gpt-5-image", cachePath)).toBe("chat");
+ });
+
+ test("catalog non-text output outranks an innocent name and a chat-shaped flag", () => {
+ expect(classifyChatCapability("nano-banana-pro", cachePath)).toBe("not-chat");
+ });
+
+ test("a mixed audio and text output is chat", () => {
+ expect(classifyChatCapability("qwen-audio-3.0-realtime-plus", cachePath)).toBe("chat");
+ });
+
+ test.each([
+ ["image", "gpt-image-2.5-flare"],
+ ["video", "gemini-omni-1.1-flash"],
+ ["audio", "qwen-audio-3.0-tts-flash"],
+ ["embeddings", "gemini-embedding-2"],
+ ["transcription", "mai-transcribe-2"],
+ ["speech", "mai-voice-2"],
+ ["rerank", "llama-nemotron-rerank-vl-1b-v2"],
+ ["decisions", "jev-1.13"],
+ ])("a live singleton %s output denies chat", (_output, modelId) => {
+ expect(classifyChatCapability(modelId, cachePath)).toBe("not-chat");
+ });
+
+ test.each([
+ ["null", "contract-null-output-with-tools"],
+ ["empty", "contract-empty-output-with-thinking"],
+ ])("a contract-only %s output list falls through to chat-shaped flags", (_case, modelId) => {
+ expect(classifyChatCapability(modelId, cachePath)).toBe("chat");
+ });
+
+ test("text output outranks videoOutput:true in the contract-only disagreement", () => {
+ expect(classifyChatCapability("contract-video-output-with-text", cachePath)).toBe("chat");
+ });
+
+ test("an alias is indexed the same way as its distinct canonical id", () => {
+ expect(classifyChatCapability("gemini-3.1-flash-image", cachePath)).toBe("chat");
+ expect(classifyChatCapability("google/flash-image-3.1", cachePath)).toBe("chat");
+ });
+
+ // Contract-only route/name fallbacks: these strings are deliberately absent
+ // from the cited live generation, as required by steps 1, 5, 6 and 8.
+ test("a wildcard route remains not-chat before catalog lookup", () => {
+ expect(classifyChatCapability("gemini/*", cachePath)).toBe("not-chat");
+ });
+
+ test.each(["unpublished-image-generator", "unpublished-model-t2v"])(
+ "an absent model still uses the non-chat name rules: %s",
+ (modelId) => {
+ expect(classifyChatCapability(modelId, cachePath)).toBe("not-chat");
+ }
+ );
+
+ test("an absent model with no matching name rule remains unknown", () => {
+ expect(classifyChatCapability("unpublished-chat-model", cachePath)).toBe("unknown");
+ });
+});
diff --git a/packages/cli/src/proxy-server.ts b/packages/cli/src/proxy-server.ts
index 13ef8c5a..89313314 100644
--- a/packages/cli/src/proxy-server.ts
+++ b/packages/cli/src/proxy-server.ts
@@ -478,7 +478,18 @@ export async function createProxyServer(
// If resolver says use direct-api, resolve credentials via the authority.
if (resolution.category === "direct-api") {
const resolved = resolveRemoteProvider(resolveTarget);
- if (!resolved) return null;
+ if (!resolved) {
+ // A KNOWN provider name that resolves to nothing has no endpoint: it
+ // declares no static baseUrl, no set `baseUrlEnvVars`, and not
+ // `buildsOwnEndpoint`. Say that here, because everything downstream of
+ // this null (OpenRouter fallback, or a 400 on an explicit spec) reads as
+ // "my key is missing" — which is how `vertex@` sent users looking for a
+ // key that was never involved.
+ log(
+ `[Proxy] No remote provider resolved for "${resolveTarget}" — no endpoint is configured for it (not a credential problem)`
+ );
+ return null;
+ }
// Skip 'openrouter' provider here - it uses the existing OpenRouterHandler
if (resolved.provider.name === "openrouter") {
diff --git a/packages/cli/src/tui/components/RoutingContent.tsx b/packages/cli/src/tui/components/RoutingContent.tsx
index 78680c15..b7603612 100644
--- a/packages/cli/src/tui/components/RoutingContent.tsx
+++ b/packages/cli/src/tui/components/RoutingContent.tsx
@@ -43,7 +43,7 @@ export const PROVIDER_REASONS: Record<string, string> = {
"openai-codex": "OpenAI Codex (Responses API)",
zai: "Z.AI API",
ollamacloud: "Cloud Ollama",
- vertex: "Vertex AI Express",
+ vertex: "Vertex AI (ADC)",
openrouter: "Fallback: 580+ models",
};