From 447c5f75845c463a83c5109aa476c417f7b6846e Mon Sep 17 00:00:00 2001
From: Christiaan Arnoldus <christiaan.arnoldus@outlook.com>
Date: Fri, 14 Aug 2026 16:40:48 +0200
Subject: [PATCH 01/12] feat(ai-gateway): add Vertex user BYOK

---
 .../organizations/byok/BYOKKeysManager.tsx    | 102 +++++++++++++-----
 apps/web/src/lib/ai-gateway/byok/index.ts     |  13 ++-
 .../lib/ai-gateway/llm-proxy-helpers.test.ts  |  25 +++++
 .../src/lib/ai-gateway/llm-proxy-helpers.ts   |  35 ++++--
 .../src/lib/ai-gateway/processUsage.test.ts   |  27 +++++
 apps/web/src/lib/ai-gateway/processUsage.ts   |  19 +++-
 .../openrouter/inference-provider-id.test.ts  |  17 +++
 .../openrouter/inference-provider-id.ts       |  34 +++++-
 .../inject-extra-provider-models.ts           |  11 +-
 .../ai-gateway/providers/openrouter/types.ts  |  10 +-
 .../ai-gateway/providers/vercel/index.test.ts |  53 +++++++++
 .../lib/ai-gateway/providers/vercel/index.ts  |  31 ++++--
 apps/web/src/routers/byok-router.test.ts      |  50 +++++++++
 apps/web/src/routers/byok-router.ts           |  26 ++++-
 14 files changed, 398 insertions(+), 55 deletions(-)

diff --git a/apps/web/src/components/organizations/byok/BYOKKeysManager.tsx b/apps/web/src/components/organizations/byok/BYOKKeysManager.tsx
index 00f677ab16..d6ed491a63 100644
--- a/apps/web/src/components/organizations/byok/BYOKKeysManager.tsx
+++ b/apps/web/src/components/organizations/byok/BYOKKeysManager.tsx
@@ -44,6 +44,7 @@ import {
   UserByokProviderIdSchema,
   VercelUserByokInferenceProviderIdSchema,
   AwsCredentialsSchema,
+  VertexCredentialsSchema,
   type VercelUserByokInferenceProviderId,
 } from '@/lib/ai-gateway/providers/openrouter/inference-provider-id';
 import { DIRECT_BYOK_PROVIDERS_META } from '@/lib/ai-gateway/providers/direct-byok/direct-byok-meta';
@@ -66,6 +67,7 @@ const VERCEL_BYOK_PROVIDER_NAMES = {
   moonshotai: 'Moonshot AI',
   novita: 'Novita',
   perplexity: 'Perplexity',
+  vertex: 'Google Vertex AI',
   xai: 'SpaceXAI',
   xiaomi: 'Xiaomi (pay as you go)',
   zai: 'Z.ai (pay as you go)',
@@ -151,7 +153,7 @@ type BYOKDialogState = {
   selectedProvider: string;
   apiKey: string;
   showApiKey: boolean;
-  awsCredentialError: string | null;
+  credentialError: string | null;
 };
 
 const INITIAL_BYOK_DIALOG_STATE: BYOKDialogState = {
@@ -160,7 +162,7 @@ const INITIAL_BYOK_DIALOG_STATE: BYOKDialogState = {
   selectedProvider: '',
   apiKey: '',
   showApiKey: false,
-  awsCredentialError: null,
+  credentialError: null,
 };
 
 function updateBYOKDialogState(state: BYOKDialogState, update: Partial<BYOKDialogState>) {
@@ -172,15 +174,15 @@ export function BYOKKeysManager({ organizationId }: BYOKKeysManagerProps) {
     updateBYOKDialogState,
     INITIAL_BYOK_DIALOG_STATE
   );
-  const { isDialogOpen, editingKeyId, selectedProvider, apiKey, showApiKey, awsCredentialError } =
+  const { isDialogOpen, editingKeyId, selectedProvider, apiKey, showApiKey, credentialError } =
     dialogState;
   const setIsDialogOpen = (isDialogOpen: boolean) => updateDialogState({ isDialogOpen });
   const setEditingKeyId = (editingKeyId: string | null) => updateDialogState({ editingKeyId });
   const setSelectedProvider = (selectedProvider: string) => updateDialogState({ selectedProvider });
   const setApiKey = (apiKey: string) => updateDialogState({ apiKey });
   const setShowApiKey = (showApiKey: boolean) => updateDialogState({ showApiKey });
-  const setAwsCredentialError = (awsCredentialError: string | null) =>
-    updateDialogState({ awsCredentialError });
+  const setCredentialError = (credentialError: string | null) =>
+    updateDialogState({ credentialError });
   const trpc = useTRPC();
   const queryClient = useQueryClient();
   const confirm = useConfirm();
@@ -274,17 +276,28 @@ export function BYOKKeysManager({ organizationId }: BYOKKeysManagerProps) {
     return keys?.some(k => k.provider_id === providerSlug) ?? false;
   };
 
-  const validateAwsCredentials = (value: string): string | null => {
+  const validateStructuredCredentials = (providerId: string, value: string): string | null => {
     if (!value) return null;
+    const schema =
+      providerId === VercelUserByokInferenceProviderIdSchema.enum.bedrock
+        ? AwsCredentialsSchema
+        : providerId === VercelUserByokInferenceProviderIdSchema.enum.vertex
+          ? VertexCredentialsSchema
+          : null;
+    if (!schema) return null;
     let parsed: unknown;
     try {
       parsed = JSON.parse(value);
     } catch {
-      return 'Invalid JSON — please enter a valid JSON object.';
+      return 'Invalid JSON. Enter a valid JSON object.';
     }
-    const result = AwsCredentialsSchema.safeParse(parsed);
+    const result = schema.safeParse(parsed);
     if (!result.success) {
-      return `Invalid AWS credentials:\n${z.prettifyError(result.error)}`;
+      const providerName =
+        providerId === VercelUserByokInferenceProviderIdSchema.enum.bedrock
+          ? 'AWS'
+          : 'Google Vertex';
+      return `Invalid ${providerName} credentials:\n${z.prettifyError(result.error)}`;
     }
     return null;
   };
@@ -295,15 +308,13 @@ export function BYOKKeysManager({ organizationId }: BYOKKeysManagerProps) {
     setSelectedProvider('');
     setApiKey('');
     setShowApiKey(false);
-    setAwsCredentialError(null);
+    setCredentialError(null);
   };
 
   const handleSave = () => {
-    if (selectedProvider === VercelUserByokInferenceProviderIdSchema.enum.bedrock) {
-      const error = validateAwsCredentials(apiKey);
-      setAwsCredentialError(error);
-      if (error) return;
-    }
+    const error = validateStructuredCredentials(selectedProvider, apiKey);
+    setCredentialError(error);
+    if (error) return;
     if (editingKeyId) {
       updateMutation.mutate({
         ...(organizationId && { organizationId }),
@@ -526,7 +537,10 @@ export function BYOKKeysManager({ organizationId }: BYOKKeysManagerProps) {
                 <Label htmlFor="provider">Provider</Label>
                 <Select
                   value={selectedProvider}
-                  onValueChange={setSelectedProvider}
+                  onValueChange={providerId => {
+                    setSelectedProvider(providerId);
+                    setCredentialError(null);
+                  }}
                   disabled={!!editingKeyId}
                 >
                   <SelectTrigger id="provider">
@@ -568,26 +582,44 @@ export function BYOKKeysManager({ organizationId }: BYOKKeysManagerProps) {
                 <Label htmlFor="apiKey">
                   {selectedProvider === VercelUserByokInferenceProviderIdSchema.enum.bedrock
                     ? 'AWS Credentials'
-                    : 'API Key'}
+                    : selectedProvider === VercelUserByokInferenceProviderIdSchema.enum.vertex
+                      ? 'Google Vertex Credentials'
+                      : 'API Key'}
                 </Label>
-                {selectedProvider === VercelUserByokInferenceProviderIdSchema.enum.bedrock ? (
+                {selectedProvider === VercelUserByokInferenceProviderIdSchema.enum.bedrock ||
+                selectedProvider === VercelUserByokInferenceProviderIdSchema.enum.vertex ? (
                   <>
                     <textarea
                       id="apiKey"
                       value={apiKey}
                       onChange={e => {
                         setApiKey(e.target.value);
-                        setAwsCredentialError(validateAwsCredentials(e.target.value));
+                        setCredentialError(null);
                       }}
-                      placeholder='{"accessKeyId": "...", "secretAccessKey": "...", "region": "us-east-1"}'
+                      onBlur={e =>
+                        setCredentialError(
+                          validateStructuredCredentials(selectedProvider, e.target.value)
+                        )
+                      }
+                      placeholder={
+                        selectedProvider === VercelUserByokInferenceProviderIdSchema.enum.bedrock
+                          ? '{"accessKeyId": "...", "secretAccessKey": "...", "region": "us-east-1"}'
+                          : '{"project": "...", "location": "us-east5", "googleCredentials": {"clientEmail": "...", "privateKey": "..."}}'
+                      }
                       className="border-input bg-background placeholder:text-muted-foreground focus-visible:ring-ring flex min-h-20 w-full rounded-md border px-3 py-2 text-sm focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50"
-                      rows={4}
-                      aria-label="AWS credentials"
+                      rows={6}
+                      aria-label={
+                        selectedProvider === VercelUserByokInferenceProviderIdSchema.enum.bedrock
+                          ? 'AWS credentials'
+                          : 'Google Vertex credentials'
+                      }
+                      aria-invalid={credentialError ? true : undefined}
+                      aria-describedby={credentialError ? 'credential-error' : undefined}
                     />
-                    {awsCredentialError && (
-                      <Alert variant="destructive">
+                    {credentialError && (
+                      <Alert id="credential-error" variant="destructive">
                         <AlertDescription className="whitespace-break-spaces">
-                          {awsCredentialError}
+                          {credentialError}
                         </AlertDescription>
                       </Alert>
                     )}
@@ -630,6 +662,23 @@ export function BYOKKeysManager({ organizationId }: BYOKKeysManagerProps) {
                     </AlertDescription>
                   </Alert>
                 )}
+                {selectedProvider === VercelUserByokInferenceProviderIdSchema.enum.vertex && (
+                  <Alert>
+                    <Info className="size-4" />
+                    <AlertDescription>
+                      <p>Enter your Google Cloud project, Vertex location, and service account:</p>
+                      <code className="mt-1 block text-xs break-all">
+                        {
+                          '{"project": "...", "location": "us-east5", "googleCredentials": {"clientEmail": "...", "privateKey": "..."}}'
+                        }
+                      </code>
+                      <p className="mt-1">
+                        Enable the Vertex AI API and grant the service account permission to invoke
+                        the models you use. Claude models may also require access in Model Garden.
+                      </p>
+                    </AlertDescription>
+                  </Alert>
+                )}
                 {editingKeyId ? (
                   <Alert>
                     <Lock className="size-4" />
@@ -722,8 +771,7 @@ export function BYOKKeysManager({ organizationId }: BYOKKeysManagerProps) {
                 disabled={
                   !selectedProvider ||
                   !apiKey ||
-                  (selectedProvider === VercelUserByokInferenceProviderIdSchema.enum.bedrock &&
-                    !!awsCredentialError) ||
+                  !!credentialError ||
                   createMutation.isPending ||
                   updateMutation.isPending
                 }
diff --git a/apps/web/src/lib/ai-gateway/byok/index.ts b/apps/web/src/lib/ai-gateway/byok/index.ts
index dd7700b909..a420296bd0 100644
--- a/apps/web/src/lib/ai-gateway/byok/index.ts
+++ b/apps/web/src/lib/ai-gateway/byok/index.ts
@@ -6,7 +6,7 @@ import { decryptApiKey } from '@/lib/ai-gateway/byok/encryption';
 import { BYOK_ENCRYPTION_KEY } from '@/lib/config.server';
 import {
   UserByokProviderIdSchema,
-  VercelUserByokInferenceProviderIdSchema,
+  getVercelUserByokProviderIdForEndpoint,
   type UserByokProviderId,
 } from '@/lib/ai-gateway/providers/openrouter/inference-provider-id';
 import { isCodestralModel } from '@/lib/ai-gateway/providers/mistral';
@@ -22,10 +22,13 @@ export async function getModelUserByokProviders(modelId: string): Promise<UserBy
     console.error('[getModelUserByokProviders] no Vercel model metadata for model %s', modelId);
     return [];
   }
-  const providers: UserByokProviderId[] =
-    vercelModelMetadata[mapModelIdToVercel(modelId)]?.endpoints
-      .map(ep => VercelUserByokInferenceProviderIdSchema.safeParse(ep.provider_name ?? ep.tag).data)
-      .filter(providerId => providerId !== undefined) ?? [];
+  const providers: UserByokProviderId[] = [
+    ...new Set(
+      vercelModelMetadata[mapModelIdToVercel(modelId)]?.endpoints
+        .map(ep => getVercelUserByokProviderIdForEndpoint(ep.provider_name ?? ep.tag))
+        .filter(providerId => providerId !== undefined) ?? []
+    ),
+  ];
   if (providers.length === 0) {
     console.debug(`[getModelUserByokProviders] no user byok providers for ${modelId}`);
     return [];
diff --git a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
index 09b12f27e7..de0932fc90 100644
--- a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
+++ b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
@@ -705,6 +705,31 @@ describe('parseEmbeddingUsageFromResponse', () => {
     expect(result.cost_mUsd).toBe(50);
   });
 
+  it('should extract Vercel system credential fallback', () => {
+    const response = makeResponse({
+      providerMetadata: {
+        gateway: {
+          cost: '0.00005',
+          marketCost: '0.00004',
+          routing: {
+            modelAttempts: [
+              {
+                success: true,
+                providerAttempts: [{ provider: 'vertex', credentialType: 'system', success: true }],
+              },
+            ],
+          },
+        },
+      },
+    });
+
+    const result = parseEmbeddingUsageFromResponse(response, 200);
+
+    expect(result.is_byok).toBe(false);
+    expect(result.cost_mUsd).toBe(50);
+    expect(result.market_cost).toBe(40);
+  });
+
   it('should default to 0 cost when upstream cost field is absent', () => {
     const response = makeResponse({
       usage: { prompt_tokens: 1000, total_tokens: 1000 },
diff --git a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
index fef2352e0d..9deb90488c 100644
--- a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
+++ b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
@@ -3,6 +3,7 @@ import * as z from 'zod';
 import { FEATURE_HEADER, type FeatureValue } from '@/lib/feature-detection';
 import {
   countAndStoreUsage,
+  didUseUserByok,
   logMicrodollarUsage,
   processTokenData,
 } from '@/lib/ai-gateway/processUsage';
@@ -40,11 +41,15 @@ import type {
   MicrodollarUsageContext,
   MicrodollarUsageStats,
   PromptInfo,
+  VercelProviderMetaData,
 } from '@/lib/ai-gateway/processUsage.types';
 import { detectContextOverflow } from '@/lib/ai-gateway/context-overflow';
 import { KILO_AUTO_BALANCED_MODEL, KILO_AUTO_FREE_MODEL } from '@/lib/ai-gateway/auto-model';
 import type { GatewayChatApiKind, ProviderId } from '@/lib/ai-gateway/providers/types';
-import { computeOpenRouterCostFields } from '@/lib/ai-gateway/processUsage.shared';
+import {
+  computeOpenRouterCostFields,
+  extractVercelIsByok,
+} from '@/lib/ai-gateway/processUsage.shared';
 import { persistExperimentAttribution } from '@/lib/ai-gateway/experiments/persist';
 import { ProxyErrorType } from '@/lib/proxy-error-types';
 import { getInferenceProvider } from '@/lib/ai-gateway/providers/kilo-exclusive-model';
@@ -940,6 +945,7 @@ type EmbeddingUsage = {
   prompt_tokens: number;
   total_tokens: number;
   cost?: number;
+  is_byok?: boolean | null;
 };
 
 type EmbeddingResponse = {
@@ -947,6 +953,8 @@ type EmbeddingResponse = {
   object: 'list';
   model: string;
   usage: EmbeddingUsage;
+  providerMetadata?: VercelProviderMetaData;
+  provider_metadata?: VercelProviderMetaData;
 };
 
 type TranscriptionUsage = {
@@ -971,9 +979,17 @@ export function parseEmbeddingUsageFromResponse(
   statusCode: number
 ): MicrodollarUsageStats {
   const json: EmbeddingResponse = JSON.parse(responseText);
+  const providerMetadata = json.providerMetadata ?? json.provider_metadata;
+  const gatewayCost = Number(providerMetadata?.gateway?.cost);
+  const gatewayMarketCost = Number(providerMetadata?.gateway?.marketCost);
 
   // Upstream providers (OpenRouter, Vercel) include cost in USD → convert to microdollars.
-  const cost_mUsd = json.usage.cost != null ? toMicrodollars(json.usage.cost) : 0;
+  const cost_mUsd =
+    json.usage.cost != null
+      ? toMicrodollars(json.usage.cost)
+      : Number.isFinite(gatewayCost)
+        ? toMicrodollars(gatewayCost)
+        : 0;
 
   return {
     messageId: json.id ?? null,
@@ -986,7 +1002,8 @@ export function parseEmbeddingUsageFromResponse(
     cacheHitTokens: 0,
     cacheWriteTokens: 0,
     cost_mUsd,
-    is_byok: null,
+    market_cost: Number.isFinite(gatewayMarketCost) ? toMicrodollars(gatewayMarketCost) : undefined,
+    is_byok: json.usage.is_byok ?? extractVercelIsByok(providerMetadata?.gateway),
     upstream_id: null,
     finish_reason: null,
     latency: null,
@@ -1080,13 +1097,19 @@ export function countAndStoreEmbeddingUsage(
       }
 
       // Preserve the real upstream cost for analytics before zeroing for BYOK
-      usageStats.market_cost = usageStats.cost_mUsd;
+      usageStats.market_cost ??= usageStats.cost_mUsd;
 
-      if (usageContext.user_byok) {
+      const usedUserByok = didUseUserByok(usageStats, usageContext);
+      if (usedUserByok) {
         usageStats.cost_mUsd = 0;
       }
 
-      return logMicrodollarUsage(usageStats, usageContext);
+      return logMicrodollarUsage(
+        usageStats,
+        usedUserByok === usageContext.user_byok
+          ? usageContext
+          : { ...usageContext, user_byok: usedUserByok }
+      );
     })
   );
 }
diff --git a/apps/web/src/lib/ai-gateway/processUsage.test.ts b/apps/web/src/lib/ai-gateway/processUsage.test.ts
index 50fde503ac..11e968fc29 100644
--- a/apps/web/src/lib/ai-gateway/processUsage.test.ts
+++ b/apps/web/src/lib/ai-gateway/processUsage.test.ts
@@ -4,6 +4,7 @@ import {
   extractPromptInfo,
   extractUsageContextInfo,
   countAndStoreUsage,
+  didUseUserByok,
   parseMicrodollarUsageFromStream,
   parseMicrodollarUsageFromString,
   mapToUsageStats,
@@ -43,6 +44,32 @@ import { PgDialect } from 'drizzle-orm/pg-core';
 // Note: Legacy banned_ja4/whitelist_ja4 tests removed - abuse classification
 // is now handled by the external abuse detection service (src/lib/abuse-service.ts)
 
+describe('didUseUserByok', () => {
+  const usageStats = { is_byok: true } as MicrodollarUsageStats;
+  const usageContext = {
+    provider: 'vercel',
+    user_byok: true,
+  } as MicrodollarUsageContext;
+
+  test('accepts confirmed Vercel BYOK usage', () => {
+    expect(didUseUserByok(usageStats, usageContext)).toBe(true);
+  });
+
+  test('rejects confirmed Vercel system credential fallback', () => {
+    expect(didUseUserByok({ ...usageStats, is_byok: false }, usageContext)).toBe(false);
+  });
+
+  test('preserves BYOK when Vercel omits credential evidence', () => {
+    expect(didUseUserByok({ ...usageStats, is_byok: null }, usageContext)).toBe(true);
+  });
+
+  test('preserves non-Vercel user BYOK behavior', () => {
+    expect(
+      didUseUserByok({ ...usageStats, is_byok: false }, { ...usageContext, provider: 'openrouter' })
+    ).toBe(true);
+  });
+});
+
 describe('processOpenRouterUsage', () => {
   const coreProps = {
     messageId: 'test-message-id',
diff --git a/apps/web/src/lib/ai-gateway/processUsage.ts b/apps/web/src/lib/ai-gateway/processUsage.ts
index 5100c6ac95..addb27e942 100644
--- a/apps/web/src/lib/ai-gateway/processUsage.ts
+++ b/apps/web/src/lib/ai-gateway/processUsage.ts
@@ -1304,12 +1304,27 @@ export async function processTokenData(
   usageStats.market_cost ??= usageStats.cost_mUsd;
   usageStats.cost_mUsd = customCost_mUsd ?? usageStats.cost_mUsd;
 
-  if ((await isFreeModel(usageContext.requested_model)) || usageContext.user_byok) {
+  const usedUserByok = didUseUserByok(usageStats, usageContext);
+  if ((await isFreeModel(usageContext.requested_model)) || usedUserByok) {
     usageStats.cost_mUsd = 0;
     usageStats.cacheDiscount_mUsd = 0;
   }
 
-  return logMicrodollarUsage(usageStats, usageContext);
+  return logMicrodollarUsage(
+    usageStats,
+    usedUserByok === usageContext.user_byok
+      ? usageContext
+      : { ...usageContext, user_byok: usedUserByok }
+  );
+}
+
+export function didUseUserByok(
+  usageStats: MicrodollarUsageStats,
+  usageContext: MicrodollarUsageContext
+): boolean {
+  return (
+    usageContext.user_byok && (usageContext.provider !== 'vercel' || usageStats.is_byok !== false)
+  );
 }
 
 async function useGenerationLookup(
diff --git a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts
index 539992af63..12d1c6003a 100644
--- a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts
+++ b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts
@@ -1,8 +1,12 @@
 import {
   DirectUserByokInferenceProviderIdSchema,
+  getVercelUserByokProviderIdForEndpoint,
+  normalizeVercelInferenceProviderIdForRouting,
   openRouterToVercelInferenceProviderId,
   OpenRouterInferenceProviderIdSchema,
   VercelInferenceProviderIdSchema,
+  VercelNonUserByokInferenceProviderIdSchema,
+  VercelUserByokInferenceProviderIdSchema,
 } from './inference-provider-id';
 
 describe('inference provider ids', () => {
@@ -25,4 +29,17 @@ describe('inference provider ids', () => {
   test('maps the OpenRouter Claude AWS provider to its Vercel provider id', () => {
     expect(openRouterToVercelInferenceProviderId('claude-on-aws')).toBe('claudeaws');
   });
+
+  test('promotes Vertex to a user BYOK provider', () => {
+    expect(VercelUserByokInferenceProviderIdSchema.safeParse('vertex').success).toBe(true);
+    expect(VercelNonUserByokInferenceProviderIdSchema.safeParse('vertex').success).toBe(false);
+    expect(openRouterToVercelInferenceProviderId('google-vertex')).toBe('vertex');
+  });
+
+  test('uses the Vertex user key for Vertex Anthropic endpoints', () => {
+    expect(normalizeVercelInferenceProviderIdForRouting('vertexAnthropic')).toBe('vertex');
+    expect(getVercelUserByokProviderIdForEndpoint('vertexAnthropic')).toBe('vertex');
+    expect(getVercelUserByokProviderIdForEndpoint('vertex')).toBe('vertex');
+    expect(getVercelUserByokProviderIdForEndpoint('unsupported')).toBeUndefined();
+  });
 });
diff --git a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts
index 454051a20e..fc45f480c1 100644
--- a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts
+++ b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts
@@ -92,6 +92,7 @@ export const VercelUserByokInferenceProviderIdSchema = z.enum([
   'moonshotai',
   'novita',
   'perplexity',
+  'vertex',
   'xai',
   'xiaomi',
   'zai',
@@ -146,6 +147,7 @@ export const UserByokTestModels = {
   [VercelUserByokInferenceProviderIdSchema.enum.mistral]: 'mistral/mistral-medium-3.5',
   [VercelUserByokInferenceProviderIdSchema.enum.openai]: 'openai/gpt-5-nano',
   [VercelUserByokInferenceProviderIdSchema.enum.perplexity]: 'perplexity/sonar',
+  [VercelUserByokInferenceProviderIdSchema.enum.vertex]: 'google/gemini-2.5-flash-lite',
   [VercelUserByokInferenceProviderIdSchema.enum.xai]: 'xai/grok-4.1-fast-non-reasoning',
   [VercelUserByokInferenceProviderIdSchema.enum.xiaomi]: 'xiaomi/mimo-v2-flash',
   [VercelUserByokInferenceProviderIdSchema.enum.zai]: 'zai/glm-4.7-flash',
@@ -203,7 +205,6 @@ export const VercelNonUserByokInferenceProviderIdSchema = z.enum([
   'stepfun',
   'streamlake',
   'togetherai',
-  'vertex',
   'vertexAnthropic',
   'voyage',
   'wafer',
@@ -225,7 +226,7 @@ const openRouterToVercelInferenceProviderMapping = {
   [OpenRouterInferenceProviderIdSchema.enum['google-ai-studio']]:
     VercelUserByokInferenceProviderIdSchema.enum.google,
   [OpenRouterInferenceProviderIdSchema.enum['google-vertex']]:
-    VercelNonUserByokInferenceProviderIdSchema.enum.vertex,
+    VercelUserByokInferenceProviderIdSchema.enum.vertex,
   [OpenRouterInferenceProviderIdSchema.enum.seed]:
     VercelNonUserByokInferenceProviderIdSchema.enum.bytedance,
   [OpenRouterInferenceProviderIdSchema.enum['z-ai']]:
@@ -247,6 +248,24 @@ export function openRouterToVercelInferenceProviderId(providerId: string) {
   return openRouterToVercelInferenceProviderMapping[normalizedProviderId] ?? normalizedProviderId;
 }
 
+export function getVercelUserByokProviderIdForEndpoint(
+  providerId: string | undefined
+): VercelUserByokInferenceProviderId | undefined {
+  return VercelUserByokInferenceProviderIdSchema.safeParse(
+    normalizeVercelInferenceProviderIdForRouting(providerId)
+  ).data;
+}
+
+export function normalizeVercelInferenceProviderIdForRouting(providerId: string): string;
+export function normalizeVercelInferenceProviderIdForRouting(
+  providerId: string | undefined
+): string | undefined;
+export function normalizeVercelInferenceProviderIdForRouting(providerId: string | undefined) {
+  return providerId === VercelNonUserByokInferenceProviderIdSchema.enum.vertexAnthropic
+    ? VercelUserByokInferenceProviderIdSchema.enum.vertex
+    : providerId;
+}
+
 const modelPrefixToVercelInferenceProviderMapping = {
   anthropic: VercelUserByokInferenceProviderIdSchema.enum.anthropic,
   google: VercelUserByokInferenceProviderIdSchema.enum.google,
@@ -273,3 +292,14 @@ export const AwsCredentialsSchema = z.object({
 });
 
 export type AwsCredentials = z.infer<typeof AwsCredentialsSchema>;
+
+export const VertexCredentialsSchema = z.object({
+  project: z.string().min(1),
+  location: z.string().min(1),
+  googleCredentials: z.object({
+    privateKey: z.string().min(1),
+    clientEmail: z.string().min(1),
+  }),
+});
+
+export type VertexCredentials = z.infer<typeof VertexCredentialsSchema>;
diff --git a/apps/web/src/lib/ai-gateway/providers/openrouter/inject-extra-provider-models.ts b/apps/web/src/lib/ai-gateway/providers/openrouter/inject-extra-provider-models.ts
index 9da97ee6d2..8a63733782 100644
--- a/apps/web/src/lib/ai-gateway/providers/openrouter/inject-extra-provider-models.ts
+++ b/apps/web/src/lib/ai-gateway/providers/openrouter/inject-extra-provider-models.ts
@@ -1,5 +1,6 @@
 import { mapModelIdToVercel } from '@/lib/ai-gateway/providers/vercel/mapModelIdToVercel';
 import {
+  normalizeVercelInferenceProviderIdForRouting,
   openRouterToVercelInferenceProviderId,
   VercelInferenceProviderIdSchema,
 } from '@/lib/ai-gateway/providers/openrouter/inference-provider-id';
@@ -27,7 +28,9 @@ export function injectExtraProviderModels(
       vercelModel.endpoints
         .map(
           endpoint =>
-            VercelInferenceProviderIdSchema.safeParse(endpoint.provider_name ?? endpoint.tag).data
+            VercelInferenceProviderIdSchema.safeParse(
+              normalizeVercelInferenceProviderIdForRouting(endpoint.provider_name ?? endpoint.tag)
+            ).data
         )
         .filter(p => p !== undefined)
     );
@@ -36,7 +39,11 @@ export function injectExtraProviderModels(
       const vercelProviderId = VercelInferenceProviderIdSchema.safeParse(
         openRouterToVercelInferenceProviderId(providerData.provider.slug)
       ).data;
-      const endpoint = vercelModel.endpoints.find(e => e.provider_name === vercelProviderId);
+      const endpoint = vercelModel.endpoints.find(
+        endpoint =>
+          normalizeVercelInferenceProviderIdForRouting(endpoint.provider_name ?? endpoint.tag) ===
+          vercelProviderId
+      );
       if (
         vercelProviderId &&
         endpoint &&
diff --git a/apps/web/src/lib/ai-gateway/providers/openrouter/types.ts b/apps/web/src/lib/ai-gateway/providers/openrouter/types.ts
index 989e549031..3679fa31db 100644
--- a/apps/web/src/lib/ai-gateway/providers/openrouter/types.ts
+++ b/apps/web/src/lib/ai-gateway/providers/openrouter/types.ts
@@ -2,7 +2,10 @@ import type OpenAI from 'openai';
 import type { GatewayProviderOptions } from '@ai-sdk/gateway';
 import type { AnthropicProviderOptions } from '@ai-sdk/anthropic';
 import type { ReasoningDetailUnion } from '@/lib/ai-gateway/custom-llm/reasoning-details';
-import type { AwsCredentials } from '@/lib/ai-gateway/providers/openrouter/inference-provider-id';
+import type {
+  AwsCredentials,
+  VertexCredentials,
+} from '@/lib/ai-gateway/providers/openrouter/inference-provider-id';
 import type Anthropic from '@anthropic-ai/sdk';
 
 // Base types for OpenRouter API that don't depend on other lib files
@@ -21,7 +24,10 @@ export function isOpenRouterProviderConfig(value: unknown): value is OpenRouterP
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-export type VercelInferenceProviderConfig = { apiKey: string; baseURL?: string } | AwsCredentials;
+export type VercelInferenceProviderConfig =
+  | { apiKey: string; baseURL?: string }
+  | AwsCredentials
+  | VertexCredentials;
 
 export type VercelProviderConfig = {
   gateway?: GatewayProviderOptions & {
diff --git a/apps/web/src/lib/ai-gateway/providers/vercel/index.test.ts b/apps/web/src/lib/ai-gateway/providers/vercel/index.test.ts
index cb697c6c47..5119cfc6b9 100644
--- a/apps/web/src/lib/ai-gateway/providers/vercel/index.test.ts
+++ b/apps/web/src/lib/ai-gateway/providers/vercel/index.test.ts
@@ -72,6 +72,10 @@ describe('hasCompatibleVercelInferenceProvider', () => {
     );
   });
 
+  it('accepts Google Vertex preferences for Vertex Anthropic endpoint metadata', () => {
+    expect(hasCompatibleVercelInferenceProvider(['google-vertex'], ['vertexAnthropic'])).toBe(true);
+  });
+
   it('rejects when none of the requested providers are available on Vercel', () => {
     expect(hasCompatibleVercelInferenceProvider(['google-vertex'], ['anthropic', 'bedrock'])).toBe(
       false
@@ -98,6 +102,15 @@ describe('getVercelInferenceProvidersExcludingIgnored', () => {
     ).toEqual(['anthropic', 'vertex']);
   });
 
+  it('excludes normalized Vertex Anthropic endpoints for Google Vertex ignores', () => {
+    expect(
+      getVercelInferenceProvidersExcludingIgnored(['google-vertex'], undefined, [
+        'anthropic',
+        'vertexAnthropic',
+      ])
+    ).toEqual(['anthropic']);
+  });
+
   it('intersects the available providers with only before excluding ignored providers', () => {
     expect(
       getVercelInferenceProvidersExcludingIgnored(
@@ -160,6 +173,14 @@ describe('applyVercelSettings BYOK pinning', () => {
     secretAccessKey: 'secret',
     region: 'us-east-1',
   });
+  const vertexCredentials = JSON.stringify({
+    project: 'example-project',
+    location: 'us-east5',
+    googleCredentials: {
+      privateKey: '-----BEGIN PRIVATE KEY-----\nsecret\n-----END PRIVATE KEY-----\n',
+      clientEmail: 'gateway@example-project.iam.gserviceaccount.com',
+    },
+  });
 
   it('drops a BYOK provider the caller ignored when another serving provider remains', async () => {
     const request = byokRequest(['anthropic']);
@@ -203,6 +224,38 @@ describe('applyVercelSettings BYOK pinning', () => {
       anthropic: [{ apiKey: 'sk-anthropic' }],
     });
   });
+
+  it('uses one Vertex credential key for Anthropic models served by Vertex', async () => {
+    const request = byokRequest([]);
+
+    await applyVercelSettings('anthropic/claude-sonnet-4.5', request, [
+      { decryptedAPIKey: vertexCredentials, providerId: 'vertex' },
+    ]);
+
+    expect(request.body.providerOptions?.gateway?.byok).toEqual({
+      vertex: [
+        {
+          project: 'example-project',
+          location: 'us-east5',
+          googleCredentials: {
+            privateKey: '-----BEGIN PRIVATE KEY-----\nsecret\n-----END PRIVATE KEY-----\n',
+            clientEmail: 'gateway@example-project.iam.gserviceaccount.com',
+          },
+        },
+      ],
+    });
+    expect(request.body.providerOptions?.gateway?.only).toEqual(['vertex']);
+  });
+
+  it('rejects malformed Vertex credentials without including credential contents', async () => {
+    const request = byokRequest([]);
+
+    await expect(
+      applyVercelSettings('google/gemini-2.5-flash-lite', request, [
+        { decryptedAPIKey: '{"privateKey":"secret"}', providerId: 'vertex' },
+      ])
+    ).rejects.toThrow('Failed to parse Google Vertex credentials');
+  });
 });
 
 describe('applyVercelSettings managed requests', () => {
diff --git a/apps/web/src/lib/ai-gateway/providers/vercel/index.ts b/apps/web/src/lib/ai-gateway/providers/vercel/index.ts
index 31b096848e..131bfca121 100644
--- a/apps/web/src/lib/ai-gateway/providers/vercel/index.ts
+++ b/apps/web/src/lib/ai-gateway/providers/vercel/index.ts
@@ -3,7 +3,9 @@ import type { VercelUserByokInferenceProviderId } from '@/lib/ai-gateway/provide
 import {
   DirectUserByokInferenceProviderIdSchema,
   AwsCredentialsSchema,
+  normalizeVercelInferenceProviderIdForRouting,
   openRouterToVercelInferenceProviderId,
+  VertexCredentialsSchema,
   VercelUserByokInferenceProviderIdSchema,
 } from '@/lib/ai-gateway/providers/openrouter/inference-provider-id';
 import type {
@@ -68,7 +70,9 @@ export function hasCompatibleVercelInferenceProvider(
   }
 
   return openRouterInferenceProviders.some(provider =>
-    vercelInferenceProviders.includes(openRouterToVercelInferenceProviderId(provider))
+    vercelInferenceProviders
+      .map(normalizeVercelInferenceProviderIdForRouting)
+      .includes(openRouterToVercelInferenceProviderId(provider))
   );
 }
 
@@ -82,9 +86,13 @@ export function getVercelInferenceProvidersExcludingIgnored(
     ? new Set(onlyProviders.map(openRouterToVercelInferenceProviderId))
     : null;
 
-  return vercelInferenceProviders.filter(
-    provider => !ignored.has(provider) && (!only || only.has(provider))
-  );
+  return [
+    ...new Set(
+      vercelInferenceProviders
+        .map(normalizeVercelInferenceProviderIdForRouting)
+        .filter(provider => !ignored.has(provider) && (!only || only.has(provider)))
+    ),
+  ];
 }
 
 export function passesVercelRoutingPercentage(randomSeed: string, routingPercentage: number) {
@@ -202,6 +210,14 @@ function parseAwsCredentials(input: string) {
   }
 }
 
+function parseVertexCredentials(input: string) {
+  try {
+    return VertexCredentialsSchema.parse(JSON.parse(input));
+  } catch {
+    throw new Error('Failed to parse Google Vertex credentials');
+  }
+}
+
 export function getAnthropicProviderOptionsForVercel(
   request: GatewayRequest
 ): AnthropicProviderOptions | undefined {
@@ -243,6 +259,8 @@ export function getVercelInferenceProviderConfigForUserByok(
 
   if (key === VercelUserByokInferenceProviderIdSchema.enum.bedrock) {
     list.push(parseAwsCredentials(provider.decryptedAPIKey));
+  } else if (key === VercelUserByokInferenceProviderIdSchema.enum.vertex) {
+    list.push(parseVertexCredentials(provider.decryptedAPIKey));
   } else {
     list.push({ apiKey: provider.decryptedAPIKey });
   }
@@ -288,8 +306,9 @@ export async function applyVercelSettings(
     const byokProviders =
       Object.keys(retainedByokProviders).length > 0 ? retainedByokProviders : allByokProviders;
 
-    // this is vercel specific BYOK configuration to force vercel gateway to use the BYOK API key
-    // for the user/org. If the key is invalid the request will faill - it will not fall back to bill our API key.
+    // Vercel tries these request-scoped credentials first. If they fail, Vercel may
+    // use system credentials; usage processing checks the successful credentialType
+    // so system fallback is billed rather than treated as user-funded BYOK.
     requestToMutate.body.providerOptions = {
       gateway: {
         only: Object.keys(byokProviders),
diff --git a/apps/web/src/routers/byok-router.test.ts b/apps/web/src/routers/byok-router.test.ts
index 54cdc57469..43a50f62f0 100644
--- a/apps/web/src/routers/byok-router.test.ts
+++ b/apps/web/src/routers/byok-router.test.ts
@@ -15,6 +15,15 @@ import type { User, Organization } from '@kilocode/db/schema';
 import { encryptApiKey } from '@/lib/ai-gateway/byok/encryption';
 import { BYOK_ENCRYPTION_KEY } from '@/lib/config.server';
 
+const VERTEX_CREDENTIALS = JSON.stringify({
+  project: 'example-project',
+  location: 'us-east5',
+  googleCredentials: {
+    privateKey: '-----BEGIN PRIVATE KEY-----\nsecret\n-----END PRIVATE KEY-----\n',
+    clientEmail: 'gateway@example-project.iam.gserviceaccount.com',
+  },
+});
+
 describe('BYOK Router', () => {
   let ownerUser: User;
   let memberUser: User;
@@ -171,6 +180,30 @@ describe('BYOK Router', () => {
       expect(dbKey.encrypted_api_key).toHaveProperty('authTag');
     });
 
+    test('should create a Vertex BYOK credential', async () => {
+      const caller = await createCallerForUser(ownerUser.id);
+
+      const result = await caller.byok.create({
+        organizationId: organizationA.id,
+        provider_id: 'vertex',
+        api_key: VERTEX_CREDENTIALS,
+      });
+
+      expect(result.provider_id).toBe('vertex');
+    });
+
+    test('should reject malformed Vertex credentials', async () => {
+      const caller = await createCallerForUser(ownerUser.id);
+
+      await expect(
+        caller.byok.create({
+          organizationId: organizationA.id,
+          provider_id: 'vertex',
+          api_key: '{"privateKey":"secret"}',
+        })
+      ).rejects.toThrow('Invalid credentials for provider: vertex');
+    });
+
     test('should create audit log entry', async () => {
       const caller = await createCallerForUser(ownerUser.id);
 
@@ -277,6 +310,23 @@ describe('BYOK Router', () => {
       expect(dbKey.encrypted_api_key).toHaveProperty('data');
     });
 
+    test('should reject malformed Vertex credentials on update', async () => {
+      const caller = await createCallerForUser(ownerUser.id);
+      const created = await caller.byok.create({
+        organizationId: organizationA.id,
+        provider_id: 'vertex',
+        api_key: VERTEX_CREDENTIALS,
+      });
+
+      await expect(
+        caller.byok.update({
+          organizationId: organizationA.id,
+          id: created.id,
+          api_key: '{}',
+        })
+      ).rejects.toThrow('Invalid credentials for provider: vertex');
+    });
+
     test('should create audit log entry for update', async () => {
       const caller = await createCallerForUser(ownerUser.id);
 
diff --git a/apps/web/src/routers/byok-router.ts b/apps/web/src/routers/byok-router.ts
index 360a00c45a..415ec0c7a2 100644
--- a/apps/web/src/routers/byok-router.ts
+++ b/apps/web/src/routers/byok-router.ts
@@ -23,6 +23,7 @@ import {
 import {
   UserByokProviderIdSchema,
   UserByokTestModels,
+  getVercelUserByokProviderIdForEndpoint,
   VercelUserByokInferenceProviderIdSchema,
 } from '@/lib/ai-gateway/providers/openrouter/inference-provider-id';
 import {
@@ -47,6 +48,23 @@ const MANAGED_KEY_READ_ONLY_MESSAGE =
   'This key is managed by your coding plan and is read-only. Cancel the coding plan to remove it.';
 const logByokWarning = sentryLogger('byok-key-test', 'warning');
 
+function validateVercelUserByokCredential(providerId: string, credential: string) {
+  const parsedProviderId = VercelUserByokInferenceProviderIdSchema.safeParse(providerId);
+  if (!parsedProviderId.success) return;
+
+  try {
+    getVercelInferenceProviderConfigForUserByok({
+      providerId: parsedProviderId.data,
+      decryptedAPIKey: credential,
+    });
+  } catch {
+    throw new TRPCError({
+      code: 'BAD_REQUEST',
+      message: `Invalid credentials for provider: ${providerId}`,
+    });
+  }
+}
+
 function rejectManagedKeyMutation(managementSource: 'user' | 'coding_plan') {
   if (managementSource === 'coding_plan') {
     throw new TRPCError({
@@ -86,11 +104,10 @@ async function fetchSupportedModels(): Promise<Record<string, string[]>> {
     if (!vercelModel) continue;
     if (vercelModel.type !== 'language') continue;
     for (const endpoint of vercelModel.endpoints) {
-      const providerParsed = VercelUserByokInferenceProviderIdSchema.safeParse(
+      const providerId = getVercelUserByokProviderIdForEndpoint(
         endpoint.provider_name ?? endpoint.tag
       );
-      if (!providerParsed.success) continue;
-      const providerId = providerParsed.data;
+      if (!providerId) continue;
       if (!result[providerId]) result[providerId] = [];
       result[providerId].push(openRouterModel.name + ' (' + openRouterModel.id + ')');
     }
@@ -161,6 +178,8 @@ export const byokRouter = createTRPCRouter({
         await ensureOrganizationAccess(ctx, organizationId, ORGANIZATION_BILLING_ROLES);
       }
 
+      validateVercelUserByokCredential(provider_id, api_key);
+
       // Encrypt the API key
       const encrypted = encryptApiKey(api_key, BYOK_ENCRYPTION_KEY);
 
@@ -249,6 +268,7 @@ export const byokRouter = createTRPCRouter({
       }
 
       rejectManagedKeyMutation(existingKey.management_source);
+      validateVercelUserByokCredential(existingKey.provider_id, api_key);
 
       const encrypted = encryptApiKey(api_key, BYOK_ENCRYPTION_KEY);
       const [updatedKey] = await db

From bd22878e470a8ddf7b30a50f61e88ace9ee77bf4 Mon Sep 17 00:00:00 2001
From: Christiaan Arnoldus <christiaan.arnoldus@outlook.com>
Date: Fri, 14 Aug 2026 16:47:42 +0200
Subject: [PATCH 02/12] fix(ai-gateway): narrow Vertex BYOK changes

---
 .../lib/ai-gateway/llm-proxy-helpers.test.ts  | 25 ------------
 .../src/lib/ai-gateway/llm-proxy-helpers.ts   | 35 +++-------------
 .../src/lib/ai-gateway/processUsage.test.ts   | 27 -------------
 apps/web/src/lib/ai-gateway/processUsage.ts   | 19 +--------
 .../lib/ai-gateway/providers/vercel/index.ts  | 40 +++++++++++++------
 5 files changed, 35 insertions(+), 111 deletions(-)

diff --git a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
index de0932fc90..09b12f27e7 100644
--- a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
+++ b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
@@ -705,31 +705,6 @@ describe('parseEmbeddingUsageFromResponse', () => {
     expect(result.cost_mUsd).toBe(50);
   });
 
-  it('should extract Vercel system credential fallback', () => {
-    const response = makeResponse({
-      providerMetadata: {
-        gateway: {
-          cost: '0.00005',
-          marketCost: '0.00004',
-          routing: {
-            modelAttempts: [
-              {
-                success: true,
-                providerAttempts: [{ provider: 'vertex', credentialType: 'system', success: true }],
-              },
-            ],
-          },
-        },
-      },
-    });
-
-    const result = parseEmbeddingUsageFromResponse(response, 200);
-
-    expect(result.is_byok).toBe(false);
-    expect(result.cost_mUsd).toBe(50);
-    expect(result.market_cost).toBe(40);
-  });
-
   it('should default to 0 cost when upstream cost field is absent', () => {
     const response = makeResponse({
       usage: { prompt_tokens: 1000, total_tokens: 1000 },
diff --git a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
index 9deb90488c..fef2352e0d 100644
--- a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
+++ b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
@@ -3,7 +3,6 @@ import * as z from 'zod';
 import { FEATURE_HEADER, type FeatureValue } from '@/lib/feature-detection';
 import {
   countAndStoreUsage,
-  didUseUserByok,
   logMicrodollarUsage,
   processTokenData,
 } from '@/lib/ai-gateway/processUsage';
@@ -41,15 +40,11 @@ import type {
   MicrodollarUsageContext,
   MicrodollarUsageStats,
   PromptInfo,
-  VercelProviderMetaData,
 } from '@/lib/ai-gateway/processUsage.types';
 import { detectContextOverflow } from '@/lib/ai-gateway/context-overflow';
 import { KILO_AUTO_BALANCED_MODEL, KILO_AUTO_FREE_MODEL } from '@/lib/ai-gateway/auto-model';
 import type { GatewayChatApiKind, ProviderId } from '@/lib/ai-gateway/providers/types';
-import {
-  computeOpenRouterCostFields,
-  extractVercelIsByok,
-} from '@/lib/ai-gateway/processUsage.shared';
+import { computeOpenRouterCostFields } from '@/lib/ai-gateway/processUsage.shared';
 import { persistExperimentAttribution } from '@/lib/ai-gateway/experiments/persist';
 import { ProxyErrorType } from '@/lib/proxy-error-types';
 import { getInferenceProvider } from '@/lib/ai-gateway/providers/kilo-exclusive-model';
@@ -945,7 +940,6 @@ type EmbeddingUsage = {
   prompt_tokens: number;
   total_tokens: number;
   cost?: number;
-  is_byok?: boolean | null;
 };
 
 type EmbeddingResponse = {
@@ -953,8 +947,6 @@ type EmbeddingResponse = {
   object: 'list';
   model: string;
   usage: EmbeddingUsage;
-  providerMetadata?: VercelProviderMetaData;
-  provider_metadata?: VercelProviderMetaData;
 };
 
 type TranscriptionUsage = {
@@ -979,17 +971,9 @@ export function parseEmbeddingUsageFromResponse(
   statusCode: number
 ): MicrodollarUsageStats {
   const json: EmbeddingResponse = JSON.parse(responseText);
-  const providerMetadata = json.providerMetadata ?? json.provider_metadata;
-  const gatewayCost = Number(providerMetadata?.gateway?.cost);
-  const gatewayMarketCost = Number(providerMetadata?.gateway?.marketCost);
 
   // Upstream providers (OpenRouter, Vercel) include cost in USD → convert to microdollars.
-  const cost_mUsd =
-    json.usage.cost != null
-      ? toMicrodollars(json.usage.cost)
-      : Number.isFinite(gatewayCost)
-        ? toMicrodollars(gatewayCost)
-        : 0;
+  const cost_mUsd = json.usage.cost != null ? toMicrodollars(json.usage.cost) : 0;
 
   return {
     messageId: json.id ?? null,
@@ -1002,8 +986,7 @@ export function parseEmbeddingUsageFromResponse(
     cacheHitTokens: 0,
     cacheWriteTokens: 0,
     cost_mUsd,
-    market_cost: Number.isFinite(gatewayMarketCost) ? toMicrodollars(gatewayMarketCost) : undefined,
-    is_byok: json.usage.is_byok ?? extractVercelIsByok(providerMetadata?.gateway),
+    is_byok: null,
     upstream_id: null,
     finish_reason: null,
     latency: null,
@@ -1097,19 +1080,13 @@ export function countAndStoreEmbeddingUsage(
       }
 
       // Preserve the real upstream cost for analytics before zeroing for BYOK
-      usageStats.market_cost ??= usageStats.cost_mUsd;
+      usageStats.market_cost = usageStats.cost_mUsd;
 
-      const usedUserByok = didUseUserByok(usageStats, usageContext);
-      if (usedUserByok) {
+      if (usageContext.user_byok) {
         usageStats.cost_mUsd = 0;
       }
 
-      return logMicrodollarUsage(
-        usageStats,
-        usedUserByok === usageContext.user_byok
-          ? usageContext
-          : { ...usageContext, user_byok: usedUserByok }
-      );
+      return logMicrodollarUsage(usageStats, usageContext);
     })
   );
 }
diff --git a/apps/web/src/lib/ai-gateway/processUsage.test.ts b/apps/web/src/lib/ai-gateway/processUsage.test.ts
index 11e968fc29..50fde503ac 100644
--- a/apps/web/src/lib/ai-gateway/processUsage.test.ts
+++ b/apps/web/src/lib/ai-gateway/processUsage.test.ts
@@ -4,7 +4,6 @@ import {
   extractPromptInfo,
   extractUsageContextInfo,
   countAndStoreUsage,
-  didUseUserByok,
   parseMicrodollarUsageFromStream,
   parseMicrodollarUsageFromString,
   mapToUsageStats,
@@ -44,32 +43,6 @@ import { PgDialect } from 'drizzle-orm/pg-core';
 // Note: Legacy banned_ja4/whitelist_ja4 tests removed - abuse classification
 // is now handled by the external abuse detection service (src/lib/abuse-service.ts)
 
-describe('didUseUserByok', () => {
-  const usageStats = { is_byok: true } as MicrodollarUsageStats;
-  const usageContext = {
-    provider: 'vercel',
-    user_byok: true,
-  } as MicrodollarUsageContext;
-
-  test('accepts confirmed Vercel BYOK usage', () => {
-    expect(didUseUserByok(usageStats, usageContext)).toBe(true);
-  });
-
-  test('rejects confirmed Vercel system credential fallback', () => {
-    expect(didUseUserByok({ ...usageStats, is_byok: false }, usageContext)).toBe(false);
-  });
-
-  test('preserves BYOK when Vercel omits credential evidence', () => {
-    expect(didUseUserByok({ ...usageStats, is_byok: null }, usageContext)).toBe(true);
-  });
-
-  test('preserves non-Vercel user BYOK behavior', () => {
-    expect(
-      didUseUserByok({ ...usageStats, is_byok: false }, { ...usageContext, provider: 'openrouter' })
-    ).toBe(true);
-  });
-});
-
 describe('processOpenRouterUsage', () => {
   const coreProps = {
     messageId: 'test-message-id',
diff --git a/apps/web/src/lib/ai-gateway/processUsage.ts b/apps/web/src/lib/ai-gateway/processUsage.ts
index addb27e942..5100c6ac95 100644
--- a/apps/web/src/lib/ai-gateway/processUsage.ts
+++ b/apps/web/src/lib/ai-gateway/processUsage.ts
@@ -1304,27 +1304,12 @@ export async function processTokenData(
   usageStats.market_cost ??= usageStats.cost_mUsd;
   usageStats.cost_mUsd = customCost_mUsd ?? usageStats.cost_mUsd;
 
-  const usedUserByok = didUseUserByok(usageStats, usageContext);
-  if ((await isFreeModel(usageContext.requested_model)) || usedUserByok) {
+  if ((await isFreeModel(usageContext.requested_model)) || usageContext.user_byok) {
     usageStats.cost_mUsd = 0;
     usageStats.cacheDiscount_mUsd = 0;
   }
 
-  return logMicrodollarUsage(
-    usageStats,
-    usedUserByok === usageContext.user_byok
-      ? usageContext
-      : { ...usageContext, user_byok: usedUserByok }
-  );
-}
-
-export function didUseUserByok(
-  usageStats: MicrodollarUsageStats,
-  usageContext: MicrodollarUsageContext
-): boolean {
-  return (
-    usageContext.user_byok && (usageContext.provider !== 'vercel' || usageStats.is_byok !== false)
-  );
+  return logMicrodollarUsage(usageStats, usageContext);
 }
 
 async function useGenerationLookup(
diff --git a/apps/web/src/lib/ai-gateway/providers/vercel/index.ts b/apps/web/src/lib/ai-gateway/providers/vercel/index.ts
index 131bfca121..e2fd3b22f1 100644
--- a/apps/web/src/lib/ai-gateway/providers/vercel/index.ts
+++ b/apps/web/src/lib/ai-gateway/providers/vercel/index.ts
@@ -69,11 +69,15 @@ export function hasCompatibleVercelInferenceProvider(
     return true;
   }
 
-  return openRouterInferenceProviders.some(provider =>
-    vercelInferenceProviders
-      .map(normalizeVercelInferenceProviderIdForRouting)
-      .includes(openRouterToVercelInferenceProviderId(provider))
-  );
+  return openRouterInferenceProviders.some(provider => {
+    const vercelProviderId = openRouterToVercelInferenceProviderId(provider);
+    return (
+      vercelProviderId !== undefined &&
+      vercelInferenceProviders
+        .map(providerId => normalizeVercelInferenceProviderIdForRouting(providerId))
+        .includes(vercelProviderId)
+    );
+  });
 }
 
 export function getVercelInferenceProvidersExcludingIgnored(
@@ -81,15 +85,23 @@ export function getVercelInferenceProvidersExcludingIgnored(
   onlyProviders: string[] | undefined,
   vercelInferenceProviders: string[]
 ) {
-  const ignored = new Set(ignoredProviders.map(openRouterToVercelInferenceProviderId));
+  const ignored = new Set<string>(
+    ignoredProviders
+      .map(openRouterToVercelInferenceProviderId)
+      .filter(providerId => providerId !== undefined)
+  );
   const only = onlyProviders
-    ? new Set(onlyProviders.map(openRouterToVercelInferenceProviderId))
+    ? new Set<string>(
+        onlyProviders
+          .map(openRouterToVercelInferenceProviderId)
+          .filter(providerId => providerId !== undefined)
+      )
     : null;
 
   return [
     ...new Set(
       vercelInferenceProviders
-        .map(normalizeVercelInferenceProviderIdForRouting)
+        .map(providerId => normalizeVercelInferenceProviderIdForRouting(providerId))
         .filter(provider => !ignored.has(provider) && (!only || only.has(provider)))
     ),
   ];
@@ -179,7 +191,9 @@ export function convertProviderOptions(
   const provider = requestToMutate.body.provider;
   const only = (() => {
     if (!provider?.ignore?.length) {
-      return provider?.only?.map(openRouterToVercelInferenceProviderId);
+      return provider?.only
+        ?.map(openRouterToVercelInferenceProviderId)
+        .filter(providerId => providerId !== undefined);
     }
     if (!vercelInferenceProviders) {
       throw new Error('Vercel inference provider data became unavailable during request transform');
@@ -194,7 +208,9 @@ export function convertProviderOptions(
   return {
     gateway: {
       only,
-      order: provider?.order?.map(p => openRouterToVercelInferenceProviderId(p)),
+      order: provider?.order
+        ?.map(openRouterToVercelInferenceProviderId)
+        .filter(providerId => providerId !== undefined),
       zeroDataRetention: provider?.zdr,
       disallowPromptTraining: provider?.data_collection === 'deny' || undefined,
       models: requestToMutate.body.models,
@@ -306,9 +322,7 @@ export async function applyVercelSettings(
     const byokProviders =
       Object.keys(retainedByokProviders).length > 0 ? retainedByokProviders : allByokProviders;
 
-    // Vercel tries these request-scoped credentials first. If they fail, Vercel may
-    // use system credentials; usage processing checks the successful credentialType
-    // so system fallback is billed rather than treated as user-funded BYOK.
+    // Pass request-scoped credentials and restrict routing to the corresponding providers.
     requestToMutate.body.providerOptions = {
       gateway: {
         only: Object.keys(byokProviders),

From 964be6093578027af539af991151092874961702 Mon Sep 17 00:00:00 2001
From: Christiaan Arnoldus <christiaan.arnoldus@outlook.com>
Date: Fri, 14 Aug 2026 17:15:17 +0200
Subject: [PATCH 03/12] fix(ai-gateway): preserve unknown Vercel providers

---
 .../openrouter/inference-provider-id.test.ts  | 15 +++++---
 .../openrouter/inference-provider-id.ts       | 28 +++++++-------
 .../inject-extra-provider-models.test.ts      | 37 +++++++++++++++++++
 .../inject-extra-provider-models.ts           | 13 ++-----
 .../ai-gateway/providers/vercel/index.test.ts | 35 ++++++++++++++++++
 .../lib/ai-gateway/providers/vercel/index.ts  | 29 ++++-----------
 6 files changed, 107 insertions(+), 50 deletions(-)

diff --git a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts
index 12d1c6003a..108f3bfe11 100644
--- a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts
+++ b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts
@@ -1,11 +1,11 @@
 import {
   DirectUserByokInferenceProviderIdSchema,
   getVercelUserByokProviderIdForEndpoint,
+  KnownVercelInferenceProviderIdSchema,
+  KnownVercelNonUserByokInferenceProviderIdSchema,
   normalizeVercelInferenceProviderIdForRouting,
   openRouterToVercelInferenceProviderId,
   OpenRouterInferenceProviderIdSchema,
-  VercelInferenceProviderIdSchema,
-  VercelNonUserByokInferenceProviderIdSchema,
   VercelUserByokInferenceProviderIdSchema,
 } from './inference-provider-id';
 
@@ -18,9 +18,9 @@ describe('inference provider ids', () => {
     expect(overlappingProviderIds).toEqual([]);
   });
 
-  test('direct BYOK provider ids do not overlap with Vercel provider ids', () => {
+  test('direct BYOK provider ids do not overlap with known Vercel provider ids', () => {
     const overlappingProviderIds = DirectUserByokInferenceProviderIdSchema.options.filter(
-      providerId => VercelInferenceProviderIdSchema.safeParse(providerId).success
+      providerId => KnownVercelInferenceProviderIdSchema.safeParse(providerId).success
     );
 
     expect(overlappingProviderIds).toEqual([]);
@@ -30,9 +30,14 @@ describe('inference provider ids', () => {
     expect(openRouterToVercelInferenceProviderId('claude-on-aws')).toBe('claudeaws');
   });
 
+  test('preserves provider ids that are not in the known provider registry', () => {
+    expect(openRouterToVercelInferenceProviderId('future-provider')).toBe('future-provider');
+    expect(normalizeVercelInferenceProviderIdForRouting('future-provider')).toBe('future-provider');
+  });
+
   test('promotes Vertex to a user BYOK provider', () => {
     expect(VercelUserByokInferenceProviderIdSchema.safeParse('vertex').success).toBe(true);
-    expect(VercelNonUserByokInferenceProviderIdSchema.safeParse('vertex').success).toBe(false);
+    expect(KnownVercelNonUserByokInferenceProviderIdSchema.safeParse('vertex').success).toBe(false);
     expect(openRouterToVercelInferenceProviderId('google-vertex')).toBe('vertex');
   });
 
diff --git a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts
index fc45f480c1..03266e5f9a 100644
--- a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts
+++ b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts
@@ -173,7 +173,9 @@ export const UserByokTestModels = {
   [DirectUserByokInferenceProviderIdSchema.enum['zai-coding']]: 'glm-4.7',
 } satisfies Record<UserByokProviderId, string>;
 
-export const VercelNonUserByokInferenceProviderIdSchema = z.enum([
+// This is a registry of provider IDs referenced explicitly in our mappings, not
+// an exhaustive schema for the open-ended provider IDs returned by Vercel.
+export const KnownVercelNonUserByokInferenceProviderIdSchema = z.enum([
   'alibaba',
   'arcee-ai',
   'azure',
@@ -210,30 +212,30 @@ export const VercelNonUserByokInferenceProviderIdSchema = z.enum([
   'wafer',
 ]);
 
-export const VercelInferenceProviderIdSchema = VercelUserByokInferenceProviderIdSchema.or(
-  VercelNonUserByokInferenceProviderIdSchema
+export const KnownVercelInferenceProviderIdSchema = VercelUserByokInferenceProviderIdSchema.or(
+  KnownVercelNonUserByokInferenceProviderIdSchema
 );
 
 export type OpenRouterInferenceProviderId = z.infer<typeof OpenRouterInferenceProviderIdSchema>;
 
-export type VercelInferenceProviderId = z.infer<typeof VercelInferenceProviderIdSchema>;
+export type KnownVercelInferenceProviderId = z.infer<typeof KnownVercelInferenceProviderIdSchema>;
 
 const openRouterToVercelInferenceProviderMapping = {
   [OpenRouterInferenceProviderIdSchema.enum['amazon-bedrock']]:
     VercelUserByokInferenceProviderIdSchema.enum.bedrock,
   [OpenRouterInferenceProviderIdSchema.enum['claude-on-aws']]:
-    VercelNonUserByokInferenceProviderIdSchema.enum.claudeaws,
+    KnownVercelNonUserByokInferenceProviderIdSchema.enum.claudeaws,
   [OpenRouterInferenceProviderIdSchema.enum['google-ai-studio']]:
     VercelUserByokInferenceProviderIdSchema.enum.google,
   [OpenRouterInferenceProviderIdSchema.enum['google-vertex']]:
     VercelUserByokInferenceProviderIdSchema.enum.vertex,
   [OpenRouterInferenceProviderIdSchema.enum.seed]:
-    VercelNonUserByokInferenceProviderIdSchema.enum.bytedance,
+    KnownVercelNonUserByokInferenceProviderIdSchema.enum.bytedance,
   [OpenRouterInferenceProviderIdSchema.enum['z-ai']]:
     VercelUserByokInferenceProviderIdSchema.enum.zai,
   [OpenRouterInferenceProviderIdSchema.enum.together]:
-    VercelNonUserByokInferenceProviderIdSchema.enum.togetherai,
-} as Record<string, VercelInferenceProviderId | undefined>;
+    KnownVercelNonUserByokInferenceProviderIdSchema.enum.togetherai,
+} as Record<string, KnownVercelInferenceProviderId | undefined>;
 
 export function normalizeInferenceProviderId(providerId: string): string;
 export function normalizeInferenceProviderId(providerId: string | undefined): string | undefined;
@@ -243,7 +245,7 @@ export function normalizeInferenceProviderId(providerId: string | undefined) {
   return (slashIndex >= 0 ? providerId.slice(0, slashIndex) : providerId).toLowerCase();
 }
 
-export function openRouterToVercelInferenceProviderId(providerId: string) {
+export function openRouterToVercelInferenceProviderId(providerId: string): string {
   const normalizedProviderId = normalizeInferenceProviderId(providerId);
   return openRouterToVercelInferenceProviderMapping[normalizedProviderId] ?? normalizedProviderId;
 }
@@ -261,7 +263,7 @@ export function normalizeVercelInferenceProviderIdForRouting(
   providerId: string | undefined
 ): string | undefined;
 export function normalizeVercelInferenceProviderIdForRouting(providerId: string | undefined) {
-  return providerId === VercelNonUserByokInferenceProviderIdSchema.enum.vertexAnthropic
+  return providerId === KnownVercelNonUserByokInferenceProviderIdSchema.enum.vertexAnthropic
     ? VercelUserByokInferenceProviderIdSchema.enum.vertex
     : providerId;
 }
@@ -272,14 +274,14 @@ const modelPrefixToVercelInferenceProviderMapping = {
   openai: VercelUserByokInferenceProviderIdSchema.enum.openai,
   minimax: VercelUserByokInferenceProviderIdSchema.enum.minimax,
   mistralai: VercelUserByokInferenceProviderIdSchema.enum.mistral,
-  qwen: VercelNonUserByokInferenceProviderIdSchema.enum.alibaba,
+  qwen: KnownVercelNonUserByokInferenceProviderIdSchema.enum.alibaba,
   'x-ai': VercelUserByokInferenceProviderIdSchema.enum.xai,
   'z-ai': VercelUserByokInferenceProviderIdSchema.enum.zai,
-} as Record<string, VercelInferenceProviderId | undefined>;
+} as Record<string, KnownVercelInferenceProviderId | undefined>;
 
 export function inferVercelFirstPartyInferenceProviderForModel(
   model: string
-): VercelInferenceProviderId | null {
+): KnownVercelInferenceProviderId | null {
   return isGptOssModel(model)
     ? null
     : (modelPrefixToVercelInferenceProviderMapping[model.split('/')[0]] ?? null);
diff --git a/apps/web/src/lib/ai-gateway/providers/openrouter/inject-extra-provider-models.test.ts b/apps/web/src/lib/ai-gateway/providers/openrouter/inject-extra-provider-models.test.ts
index 8ba59ce97e..8c688142ab 100644
--- a/apps/web/src/lib/ai-gateway/providers/openrouter/inject-extra-provider-models.test.ts
+++ b/apps/web/src/lib/ai-gateway/providers/openrouter/inject-extra-provider-models.test.ts
@@ -99,4 +99,41 @@ describe('injectExtraProviderModels', () => {
     expect(modelTrains(nvidia, true)).toBe(true);
     expect(modelRetainsPrompts(nvidia, true)).toBe(true);
   });
+
+  test('injects offerings for providers outside the known provider registry', () => {
+    const model = nvidiaModel();
+    const providerModelData = [
+      {
+        provider: provider('nvidia', 'NVIDIA', {
+          training: true,
+          retainsPrompts: true,
+          canPublish: false,
+        }),
+        models: [model],
+      },
+      {
+        provider: provider('future-provider', 'Future Provider', {
+          training: false,
+          retainsPrompts: false,
+          canPublish: false,
+        }),
+        models: [] as OpenRouterModel[],
+      },
+    ];
+    const vercelModels: Record<string, StoredModel> = {
+      [MODEL_SLUG]: {
+        id: MODEL_SLUG,
+        name: model.name,
+        endpoints: [
+          { provider_name: 'nvidia' },
+          { provider_name: 'future-provider', context_length: 128_000 },
+        ],
+      },
+    };
+
+    injectExtraProviderModels(vercelModels, providerModelData);
+
+    expect(providerModelData[1]?.models[0]?.slug).toBe(MODEL_SLUG);
+    expect(providerModelData[1]?.models[0]?.context_length).toBe(128_000);
+  });
 });
diff --git a/apps/web/src/lib/ai-gateway/providers/openrouter/inject-extra-provider-models.ts b/apps/web/src/lib/ai-gateway/providers/openrouter/inject-extra-provider-models.ts
index 8a63733782..332ad8e09a 100644
--- a/apps/web/src/lib/ai-gateway/providers/openrouter/inject-extra-provider-models.ts
+++ b/apps/web/src/lib/ai-gateway/providers/openrouter/inject-extra-provider-models.ts
@@ -2,7 +2,6 @@ import { mapModelIdToVercel } from '@/lib/ai-gateway/providers/vercel/mapModelId
 import {
   normalizeVercelInferenceProviderIdForRouting,
   openRouterToVercelInferenceProviderId,
-  VercelInferenceProviderIdSchema,
 } from '@/lib/ai-gateway/providers/openrouter/inference-provider-id';
 import type {
   OpenRouterModel,
@@ -26,26 +25,20 @@ export function injectExtraProviderModels(
 
     const vercelInferenceProviders = new Set(
       vercelModel.endpoints
-        .map(
-          endpoint =>
-            VercelInferenceProviderIdSchema.safeParse(
-              normalizeVercelInferenceProviderIdForRouting(endpoint.provider_name ?? endpoint.tag)
-            ).data
+        .map(endpoint =>
+          normalizeVercelInferenceProviderIdForRouting(endpoint.provider_name ?? endpoint.tag)
         )
         .filter(p => p !== undefined)
     );
 
     for (const providerData of providerModelData) {
-      const vercelProviderId = VercelInferenceProviderIdSchema.safeParse(
-        openRouterToVercelInferenceProviderId(providerData.provider.slug)
-      ).data;
+      const vercelProviderId = openRouterToVercelInferenceProviderId(providerData.provider.slug);
       const endpoint = vercelModel.endpoints.find(
         endpoint =>
           normalizeVercelInferenceProviderIdForRouting(endpoint.provider_name ?? endpoint.tag) ===
           vercelProviderId
       );
       if (
-        vercelProviderId &&
         endpoint &&
         vercelInferenceProviders.has(vercelProviderId) &&
         !providerData.models.some(m => m.slug === model.slug)
diff --git a/apps/web/src/lib/ai-gateway/providers/vercel/index.test.ts b/apps/web/src/lib/ai-gateway/providers/vercel/index.test.ts
index 5119cfc6b9..280d5231cb 100644
--- a/apps/web/src/lib/ai-gateway/providers/vercel/index.test.ts
+++ b/apps/web/src/lib/ai-gateway/providers/vercel/index.test.ts
@@ -76,6 +76,12 @@ describe('hasCompatibleVercelInferenceProvider', () => {
     expect(hasCompatibleVercelInferenceProvider(['google-vertex'], ['vertexAnthropic'])).toBe(true);
   });
 
+  it('accepts providers outside the known provider registry', () => {
+    expect(hasCompatibleVercelInferenceProvider(['future-provider'], ['future-provider'])).toBe(
+      true
+    );
+  });
+
   it('rejects when none of the requested providers are available on Vercel', () => {
     expect(hasCompatibleVercelInferenceProvider(['google-vertex'], ['anthropic', 'bedrock'])).toBe(
       false
@@ -129,6 +135,16 @@ describe('getVercelInferenceProvidersExcludingIgnored', () => {
       ])
     ).toEqual([]);
   });
+
+  it('preserves and filters providers outside the known provider registry', () => {
+    expect(
+      getVercelInferenceProvidersExcludingIgnored(['future-provider'], undefined, [
+        'anthropic',
+        'future-provider',
+        'another-future-provider',
+      ])
+    ).toEqual(['anthropic', 'another-future-provider']);
+  });
 });
 
 describe('convertProviderOptions', () => {
@@ -151,6 +167,25 @@ describe('convertProviderOptions', () => {
     expect(providerOptions.gateway?.only).toEqual(['anthropic']);
     expect(provider?.only).toEqual(['anthropic', 'amazon-bedrock']);
   });
+
+  it('passes providers outside the known provider registry through unchanged', () => {
+    const request: GatewayRequest = {
+      kind: 'chat_completions',
+      body: {
+        model: 'future/model',
+        messages: [{ role: 'user', content: 'hello' }],
+        provider: {
+          only: ['future-provider'],
+          order: ['another-future-provider'],
+        },
+      },
+    };
+
+    expect(convertProviderOptions(request, null).gateway).toMatchObject({
+      only: ['future-provider'],
+      order: ['another-future-provider'],
+    });
+  });
 });
 
 describe('applyVercelSettings BYOK pinning', () => {
diff --git a/apps/web/src/lib/ai-gateway/providers/vercel/index.ts b/apps/web/src/lib/ai-gateway/providers/vercel/index.ts
index e2fd3b22f1..8989433bec 100644
--- a/apps/web/src/lib/ai-gateway/providers/vercel/index.ts
+++ b/apps/web/src/lib/ai-gateway/providers/vercel/index.ts
@@ -71,12 +71,9 @@ export function hasCompatibleVercelInferenceProvider(
 
   return openRouterInferenceProviders.some(provider => {
     const vercelProviderId = openRouterToVercelInferenceProviderId(provider);
-    return (
-      vercelProviderId !== undefined &&
-      vercelInferenceProviders
-        .map(providerId => normalizeVercelInferenceProviderIdForRouting(providerId))
-        .includes(vercelProviderId)
-    );
+    return vercelInferenceProviders
+      .map(providerId => normalizeVercelInferenceProviderIdForRouting(providerId))
+      .includes(vercelProviderId);
   });
 }
 
@@ -85,17 +82,9 @@ export function getVercelInferenceProvidersExcludingIgnored(
   onlyProviders: string[] | undefined,
   vercelInferenceProviders: string[]
 ) {
-  const ignored = new Set<string>(
-    ignoredProviders
-      .map(openRouterToVercelInferenceProviderId)
-      .filter(providerId => providerId !== undefined)
-  );
+  const ignored = new Set(ignoredProviders.map(openRouterToVercelInferenceProviderId));
   const only = onlyProviders
-    ? new Set<string>(
-        onlyProviders
-          .map(openRouterToVercelInferenceProviderId)
-          .filter(providerId => providerId !== undefined)
-      )
+    ? new Set(onlyProviders.map(openRouterToVercelInferenceProviderId))
     : null;
 
   return [
@@ -191,9 +180,7 @@ export function convertProviderOptions(
   const provider = requestToMutate.body.provider;
   const only = (() => {
     if (!provider?.ignore?.length) {
-      return provider?.only
-        ?.map(openRouterToVercelInferenceProviderId)
-        .filter(providerId => providerId !== undefined);
+      return provider?.only?.map(openRouterToVercelInferenceProviderId);
     }
     if (!vercelInferenceProviders) {
       throw new Error('Vercel inference provider data became unavailable during request transform');
@@ -208,9 +195,7 @@ export function convertProviderOptions(
   return {
     gateway: {
       only,
-      order: provider?.order
-        ?.map(openRouterToVercelInferenceProviderId)
-        .filter(providerId => providerId !== undefined),
+      order: provider?.order?.map(openRouterToVercelInferenceProviderId),
       zeroDataRetention: provider?.zdr,
       disallowPromptTraining: provider?.data_collection === 'deny' || undefined,
       models: requestToMutate.body.models,

From 06a8442b47b46008acb6fc9a2277f741d2cdafce Mon Sep 17 00:00:00 2001
From: Christiaan Arnoldus <christiaan.arnoldus@outlook.com>
Date: Tue, 18 Aug 2026 16:10:01 +0200
Subject: [PATCH 04/12] refactor(ai-gateway): restore provider schema name

---
 .../openrouter/inference-provider-id.test.ts       |  4 ++--
 .../providers/openrouter/inference-provider-id.ts  | 14 +++++++-------
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts
index 108f3bfe11..ee26411fc6 100644
--- a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts
+++ b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts
@@ -2,10 +2,10 @@ import {
   DirectUserByokInferenceProviderIdSchema,
   getVercelUserByokProviderIdForEndpoint,
   KnownVercelInferenceProviderIdSchema,
-  KnownVercelNonUserByokInferenceProviderIdSchema,
   normalizeVercelInferenceProviderIdForRouting,
   openRouterToVercelInferenceProviderId,
   OpenRouterInferenceProviderIdSchema,
+  VercelNonUserByokInferenceProviderIdSchema,
   VercelUserByokInferenceProviderIdSchema,
 } from './inference-provider-id';
 
@@ -37,7 +37,7 @@ describe('inference provider ids', () => {
 
   test('promotes Vertex to a user BYOK provider', () => {
     expect(VercelUserByokInferenceProviderIdSchema.safeParse('vertex').success).toBe(true);
-    expect(KnownVercelNonUserByokInferenceProviderIdSchema.safeParse('vertex').success).toBe(false);
+    expect(VercelNonUserByokInferenceProviderIdSchema.safeParse('vertex').success).toBe(false);
     expect(openRouterToVercelInferenceProviderId('google-vertex')).toBe('vertex');
   });
 
diff --git a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts
index 03266e5f9a..fa753ac202 100644
--- a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts
+++ b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts
@@ -175,7 +175,7 @@ export const UserByokTestModels = {
 
 // This is a registry of provider IDs referenced explicitly in our mappings, not
 // an exhaustive schema for the open-ended provider IDs returned by Vercel.
-export const KnownVercelNonUserByokInferenceProviderIdSchema = z.enum([
+export const VercelNonUserByokInferenceProviderIdSchema = z.enum([
   'alibaba',
   'arcee-ai',
   'azure',
@@ -213,7 +213,7 @@ export const KnownVercelNonUserByokInferenceProviderIdSchema = z.enum([
 ]);
 
 export const KnownVercelInferenceProviderIdSchema = VercelUserByokInferenceProviderIdSchema.or(
-  KnownVercelNonUserByokInferenceProviderIdSchema
+  VercelNonUserByokInferenceProviderIdSchema
 );
 
 export type OpenRouterInferenceProviderId = z.infer<typeof OpenRouterInferenceProviderIdSchema>;
@@ -224,17 +224,17 @@ const openRouterToVercelInferenceProviderMapping = {
   [OpenRouterInferenceProviderIdSchema.enum['amazon-bedrock']]:
     VercelUserByokInferenceProviderIdSchema.enum.bedrock,
   [OpenRouterInferenceProviderIdSchema.enum['claude-on-aws']]:
-    KnownVercelNonUserByokInferenceProviderIdSchema.enum.claudeaws,
+    VercelNonUserByokInferenceProviderIdSchema.enum.claudeaws,
   [OpenRouterInferenceProviderIdSchema.enum['google-ai-studio']]:
     VercelUserByokInferenceProviderIdSchema.enum.google,
   [OpenRouterInferenceProviderIdSchema.enum['google-vertex']]:
     VercelUserByokInferenceProviderIdSchema.enum.vertex,
   [OpenRouterInferenceProviderIdSchema.enum.seed]:
-    KnownVercelNonUserByokInferenceProviderIdSchema.enum.bytedance,
+    VercelNonUserByokInferenceProviderIdSchema.enum.bytedance,
   [OpenRouterInferenceProviderIdSchema.enum['z-ai']]:
     VercelUserByokInferenceProviderIdSchema.enum.zai,
   [OpenRouterInferenceProviderIdSchema.enum.together]:
-    KnownVercelNonUserByokInferenceProviderIdSchema.enum.togetherai,
+    VercelNonUserByokInferenceProviderIdSchema.enum.togetherai,
 } as Record<string, KnownVercelInferenceProviderId | undefined>;
 
 export function normalizeInferenceProviderId(providerId: string): string;
@@ -263,7 +263,7 @@ export function normalizeVercelInferenceProviderIdForRouting(
   providerId: string | undefined
 ): string | undefined;
 export function normalizeVercelInferenceProviderIdForRouting(providerId: string | undefined) {
-  return providerId === KnownVercelNonUserByokInferenceProviderIdSchema.enum.vertexAnthropic
+  return providerId === VercelNonUserByokInferenceProviderIdSchema.enum.vertexAnthropic
     ? VercelUserByokInferenceProviderIdSchema.enum.vertex
     : providerId;
 }
@@ -274,7 +274,7 @@ const modelPrefixToVercelInferenceProviderMapping = {
   openai: VercelUserByokInferenceProviderIdSchema.enum.openai,
   minimax: VercelUserByokInferenceProviderIdSchema.enum.minimax,
   mistralai: VercelUserByokInferenceProviderIdSchema.enum.mistral,
-  qwen: KnownVercelNonUserByokInferenceProviderIdSchema.enum.alibaba,
+  qwen: VercelNonUserByokInferenceProviderIdSchema.enum.alibaba,
   'x-ai': VercelUserByokInferenceProviderIdSchema.enum.xai,
   'z-ai': VercelUserByokInferenceProviderIdSchema.enum.zai,
 } as Record<string, KnownVercelInferenceProviderId | undefined>;

From 512de7d632f25e554ede697da3bf803a807f41af Mon Sep 17 00:00:00 2001
From: Christiaan Arnoldus <christiaan.arnoldus@outlook.com>
Date: Thu, 20 Aug 2026 11:47:45 +0200
Subject: [PATCH 05/12] refactor(ai-gateway): restore provider type names

---
 .../providers/openrouter/inference-provider-id.test.ts |  4 ++--
 .../providers/openrouter/inference-provider-id.ts      | 10 +++++-----
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts
index ee26411fc6..8968f16606 100644
--- a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts
+++ b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.test.ts
@@ -1,10 +1,10 @@
 import {
   DirectUserByokInferenceProviderIdSchema,
   getVercelUserByokProviderIdForEndpoint,
-  KnownVercelInferenceProviderIdSchema,
   normalizeVercelInferenceProviderIdForRouting,
   openRouterToVercelInferenceProviderId,
   OpenRouterInferenceProviderIdSchema,
+  VercelInferenceProviderIdSchema,
   VercelNonUserByokInferenceProviderIdSchema,
   VercelUserByokInferenceProviderIdSchema,
 } from './inference-provider-id';
@@ -20,7 +20,7 @@ describe('inference provider ids', () => {
 
   test('direct BYOK provider ids do not overlap with known Vercel provider ids', () => {
     const overlappingProviderIds = DirectUserByokInferenceProviderIdSchema.options.filter(
-      providerId => KnownVercelInferenceProviderIdSchema.safeParse(providerId).success
+      providerId => VercelInferenceProviderIdSchema.safeParse(providerId).success
     );
 
     expect(overlappingProviderIds).toEqual([]);
diff --git a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts
index fa753ac202..85bcc5a1f2 100644
--- a/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts
+++ b/apps/web/src/lib/ai-gateway/providers/openrouter/inference-provider-id.ts
@@ -212,13 +212,13 @@ export const VercelNonUserByokInferenceProviderIdSchema = z.enum([
   'wafer',
 ]);
 
-export const KnownVercelInferenceProviderIdSchema = VercelUserByokInferenceProviderIdSchema.or(
+export const VercelInferenceProviderIdSchema = VercelUserByokInferenceProviderIdSchema.or(
   VercelNonUserByokInferenceProviderIdSchema
 );
 
 export type OpenRouterInferenceProviderId = z.infer<typeof OpenRouterInferenceProviderIdSchema>;
 
-export type KnownVercelInferenceProviderId = z.infer<typeof KnownVercelInferenceProviderIdSchema>;
+export type VercelInferenceProviderId = z.infer<typeof VercelInferenceProviderIdSchema>;
 
 const openRouterToVercelInferenceProviderMapping = {
   [OpenRouterInferenceProviderIdSchema.enum['amazon-bedrock']]:
@@ -235,7 +235,7 @@ const openRouterToVercelInferenceProviderMapping = {
     VercelUserByokInferenceProviderIdSchema.enum.zai,
   [OpenRouterInferenceProviderIdSchema.enum.together]:
     VercelNonUserByokInferenceProviderIdSchema.enum.togetherai,
-} as Record<string, KnownVercelInferenceProviderId | undefined>;
+} as Record<string, VercelInferenceProviderId | undefined>;
 
 export function normalizeInferenceProviderId(providerId: string): string;
 export function normalizeInferenceProviderId(providerId: string | undefined): string | undefined;
@@ -277,11 +277,11 @@ const modelPrefixToVercelInferenceProviderMapping = {
   qwen: VercelNonUserByokInferenceProviderIdSchema.enum.alibaba,
   'x-ai': VercelUserByokInferenceProviderIdSchema.enum.xai,
   'z-ai': VercelUserByokInferenceProviderIdSchema.enum.zai,
-} as Record<string, KnownVercelInferenceProviderId | undefined>;
+} as Record<string, VercelInferenceProviderId | undefined>;
 
 export function inferVercelFirstPartyInferenceProviderForModel(
   model: string
-): KnownVercelInferenceProviderId | null {
+): VercelInferenceProviderId | null {
   return isGptOssModel(model)
     ? null
     : (modelPrefixToVercelInferenceProviderMapping[model.split('/')[0]] ?? null);

From 48b1ee663d61c81d791d7684201da5dc25c4ac73 Mon Sep 17 00:00:00 2001
From: Christiaan Arnoldus <christiaan.arnoldus@outlook.com>
Date: Fri, 21 Aug 2026 14:43:30 +0200
Subject: [PATCH 06/12] fix(ai-gateway): recommend global Vertex location

---
 .../web/src/components/organizations/byok/BYOKKeysManager.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/web/src/components/organizations/byok/BYOKKeysManager.tsx b/apps/web/src/components/organizations/byok/BYOKKeysManager.tsx
index d6ed491a63..ed96468d5a 100644
--- a/apps/web/src/components/organizations/byok/BYOKKeysManager.tsx
+++ b/apps/web/src/components/organizations/byok/BYOKKeysManager.tsx
@@ -604,7 +604,7 @@ export function BYOKKeysManager({ organizationId }: BYOKKeysManagerProps) {
                       placeholder={
                         selectedProvider === VercelUserByokInferenceProviderIdSchema.enum.bedrock
                           ? '{"accessKeyId": "...", "secretAccessKey": "...", "region": "us-east-1"}'
-                          : '{"project": "...", "location": "us-east5", "googleCredentials": {"clientEmail": "...", "privateKey": "..."}}'
+                          : '{"project": "...", "location": "global", "googleCredentials": {"clientEmail": "...", "privateKey": "..."}}'
                       }
                       className="border-input bg-background placeholder:text-muted-foreground focus-visible:ring-ring flex min-h-20 w-full rounded-md border px-3 py-2 text-sm focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50"
                       rows={6}
@@ -669,7 +669,7 @@ export function BYOKKeysManager({ organizationId }: BYOKKeysManagerProps) {
                       <p>Enter your Google Cloud project, Vertex location, and service account:</p>
                       <code className="mt-1 block text-xs break-all">
                         {
-                          '{"project": "...", "location": "us-east5", "googleCredentials": {"clientEmail": "...", "privateKey": "..."}}'
+                          '{"project": "...", "location": "global", "googleCredentials": {"clientEmail": "...", "privateKey": "..."}}'
                         }
                       </code>
                       <p className="mt-1">

From 837933e73321caaa929d4a42389039a1f82357d7 Mon Sep 17 00:00:00 2001
From: Christiaan Arnoldus <christiaan.arnoldus@outlook.com>
Date: Fri, 21 Aug 2026 15:23:42 +0200
Subject: [PATCH 07/12] fix(ai-gateway): explain missing Vertex BYOK models

---
 .../lib/ai-gateway/llm-proxy-helpers.test.ts  | 153 ++++++++++++++++++
 .../src/lib/ai-gateway/llm-proxy-helpers.ts   |  69 ++++++++
 2 files changed, 222 insertions(+)

diff --git a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
index 08ffc66d5b..ea08d7051a 100644
--- a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
+++ b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
@@ -877,6 +877,159 @@ describe('makeErrorReadable', () => {
     expect(result).toBeUndefined();
   });
 
+  it('explains a missing model for a Vertex user BYOK request', async () => {
+    const response = Response.json(
+      {
+        error: { message: 'AI_APICallError' },
+        providerMetadata: {
+          gateway: {
+            routing: {
+              modelAttempts: [
+                {
+                  providerAttempts: [
+                    {
+                      provider: 'vertexAnthropic',
+                      credentialType: 'byok',
+                      success: false,
+                      statusCode: 404,
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        },
+      },
+      { status: 404 }
+    );
+
+    const result = await makeErrorReadable({
+      providerId: 'vercel',
+      requestedModel: 'anthropic/claude-sonnet-5',
+      request,
+      response,
+      isUserByok: true,
+    });
+
+    expect(result?.status).toBe(404);
+    await expect(result?.json()).resolves.toEqual({
+      error:
+        '[BYOK] Google Vertex AI could not find the requested model. The model might not be enabled for your Google Cloud project or selected Vertex location.',
+      error_type: 'byok_error',
+      message:
+        '[BYOK] Google Vertex AI could not find the requested model. The model might not be enabled for your Google Cloud project or selected Vertex location.',
+    });
+  });
+
+  it('does not label other Vercel BYOK 404 responses as Vertex errors', async () => {
+    const response = Response.json(
+      {
+        providerMetadata: {
+          gateway: {
+            routing: {
+              modelAttempts: [
+                {
+                  providerAttempts: [{ provider: 'anthropic', credentialType: 'byok' }],
+                },
+              ],
+            },
+          },
+        },
+      },
+      { status: 404 }
+    );
+
+    await expect(
+      makeErrorReadable({
+        providerId: 'vercel',
+        requestedModel: 'anthropic/claude-sonnet-5',
+        request,
+        response,
+        isUserByok: true,
+      })
+    ).resolves.toBeUndefined();
+  });
+
+  it('ignores unrelated attempts while matching a failed Vertex BYOK 404', async () => {
+    const response = Response.json(
+      {
+        providerMetadata: {
+          gateway: {
+            routing: {
+              modelAttempts: [
+                {},
+                {
+                  providerAttempts: [
+                    { provider: 'anthropic' },
+                    {
+                      provider: 'vertex',
+                      credentialType: 'byok',
+                      success: false,
+                      statusCode: 404,
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        },
+      },
+      { status: 404 }
+    );
+
+    const result = await makeErrorReadable({
+      providerId: 'vercel',
+      requestedModel: 'google/gemini-3.5-flash',
+      request,
+      response,
+      isUserByok: true,
+    });
+
+    expect((await result?.json()).error_type).toBe('byok_error');
+  });
+
+  it('does not use the Vertex model hint when another attempt produced the 404', async () => {
+    const response = Response.json(
+      {
+        providerMetadata: {
+          gateway: {
+            routing: {
+              modelAttempts: [
+                {
+                  providerAttempts: [
+                    {
+                      provider: 'vertexAnthropic',
+                      credentialType: 'byok',
+                      success: false,
+                      statusCode: 403,
+                    },
+                    {
+                      provider: 'anthropic',
+                      credentialType: 'system',
+                      success: false,
+                      statusCode: 404,
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        },
+      },
+      { status: 404 }
+    );
+
+    await expect(
+      makeErrorReadable({
+        providerId: 'vercel',
+        requestedModel: 'anthropic/claude-sonnet-5',
+        request,
+        response,
+        isUserByok: true,
+      })
+    ).resolves.toBeUndefined();
+  });
+
   it('returns an actionable error when no allowed provider serves the model', async () => {
     const response = Response.json(
       {
diff --git a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
index f886b4489c..5f6edebff2 100644
--- a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
+++ b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
@@ -203,6 +203,68 @@ function byokErrorMessage(status: number): string | undefined {
   return byokErrorMessages[status];
 }
 
+const vercelVertexByokErrorSchema = z.object({
+  providerMetadata: z.object({
+    gateway: z.object({
+      routing: z.object({
+        modelAttempts: z.array(
+          z.object({
+            providerAttempts: z
+              .array(
+                z.object({
+                  provider: z.string().optional(),
+                  credentialType: z.string().optional(),
+                  success: z.boolean().optional(),
+                  statusCode: z.number().optional(),
+                })
+              )
+              .optional(),
+          })
+        ),
+      }),
+    }),
+  }),
+});
+
+async function vertexByokModelNotFoundResponse(
+  providerId: ProviderId,
+  response: Response,
+  isUserByok: boolean
+) {
+  if (providerId !== 'vercel' || !isUserByok || response.status !== 404) return undefined;
+
+  let body: unknown;
+  try {
+    body = await response.clone().json();
+  } catch {
+    return undefined;
+  }
+
+  const parsedBody = vercelVertexByokErrorSchema.safeParse(body);
+  if (!parsedBody.success) return undefined;
+
+  const hasVertexByokAttempt = parsedBody.data.providerMetadata.gateway.routing.modelAttempts.some(
+    modelAttempt =>
+      modelAttempt.providerAttempts?.some(
+        providerAttempt =>
+          (providerAttempt.provider === 'vertex' ||
+            providerAttempt.provider === 'vertexAnthropic') &&
+          providerAttempt.credentialType === 'byok' &&
+          providerAttempt.success === false &&
+          providerAttempt.statusCode === 404
+      ) === true
+  );
+  if (!hasVertexByokAttempt) return undefined;
+
+  const error =
+    '[BYOK] Google Vertex AI could not find the requested model. The model might not be enabled for your Google Cloud project or selected Vertex location.';
+  warnExceptInTest(`Responding with ${response.status} ${error}`);
+  return NextResponse.json(
+    { error, error_type: ProxyErrorType.byok_error, message: error },
+    { status: response.status }
+  );
+}
+
 const noAllowedProvidersErrorSchema = z.object({
   message: z.literal('No allowed providers are available for the selected model.'),
   code: z.literal(404),
@@ -263,6 +325,13 @@ export async function makeErrorReadable({
     return undefined;
   }
 
+  const vertexByokResponse = await vertexByokModelNotFoundResponse(
+    providerId,
+    response,
+    isUserByok
+  );
+  if (vertexByokResponse) return vertexByokResponse;
+
   if (isUserByok) {
     const byokMessage = byokErrorMessage(response.status);
     if (byokMessage) {

From c328e0ca1a70c0490941671b106c35b4600e9923 Mon Sep 17 00:00:00 2001
From: Christiaan Arnoldus <christiaan.arnoldus@outlook.com>
Date: Fri, 21 Aug 2026 15:28:47 +0200
Subject: [PATCH 08/12] fix(ai-gateway): simplify Vertex BYOK hint

---
 .../src/app/api/openrouter/[...path]/route.ts |   2 +
 .../lib/ai-gateway/llm-proxy-helpers.test.ts  | 125 +-----------------
 .../src/lib/ai-gateway/llm-proxy-helpers.ts   |  62 +--------
 3 files changed, 11 insertions(+), 178 deletions(-)

diff --git a/apps/web/src/app/api/openrouter/[...path]/route.ts b/apps/web/src/app/api/openrouter/[...path]/route.ts
index 200cd4c822..de5f871ddd 100644
--- a/apps/web/src/app/api/openrouter/[...path]/route.ts
+++ b/apps/web/src/app/api/openrouter/[...path]/route.ts
@@ -1104,6 +1104,8 @@ export async function POST(request: NextRequest): Promise<NextResponseType<unkno
       request: requestBodyParsed,
       response,
       isUserByok: !!effectiveProviderContext.userByok,
+      hasVertexUserByok:
+        effectiveProviderContext.userByok?.some(byok => byok.providerId === 'vertex') ?? false,
     });
     if (errorResponse) {
       await logUnrewrittenResponse({
diff --git a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
index ea08d7051a..c6b669e73c 100644
--- a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
+++ b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
@@ -878,30 +878,7 @@ describe('makeErrorReadable', () => {
   });
 
   it('explains a missing model for a Vertex user BYOK request', async () => {
-    const response = Response.json(
-      {
-        error: { message: 'AI_APICallError' },
-        providerMetadata: {
-          gateway: {
-            routing: {
-              modelAttempts: [
-                {
-                  providerAttempts: [
-                    {
-                      provider: 'vertexAnthropic',
-                      credentialType: 'byok',
-                      success: false,
-                      statusCode: 404,
-                    },
-                  ],
-                },
-              ],
-            },
-          },
-        },
-      },
-      { status: 404 }
-    );
+    const response = Response.json({ error: { message: 'AI_APICallError' } }, { status: 404 });
 
     const result = await makeErrorReadable({
       providerId: 'vercel',
@@ -909,6 +886,7 @@ describe('makeErrorReadable', () => {
       request,
       response,
       isUserByok: true,
+      hasVertexUserByok: true,
     });
 
     expect(result?.status).toBe(404);
@@ -921,103 +899,8 @@ describe('makeErrorReadable', () => {
     });
   });
 
-  it('does not label other Vercel BYOK 404 responses as Vertex errors', async () => {
-    const response = Response.json(
-      {
-        providerMetadata: {
-          gateway: {
-            routing: {
-              modelAttempts: [
-                {
-                  providerAttempts: [{ provider: 'anthropic', credentialType: 'byok' }],
-                },
-              ],
-            },
-          },
-        },
-      },
-      { status: 404 }
-    );
-
-    await expect(
-      makeErrorReadable({
-        providerId: 'vercel',
-        requestedModel: 'anthropic/claude-sonnet-5',
-        request,
-        response,
-        isUserByok: true,
-      })
-    ).resolves.toBeUndefined();
-  });
-
-  it('ignores unrelated attempts while matching a failed Vertex BYOK 404', async () => {
-    const response = Response.json(
-      {
-        providerMetadata: {
-          gateway: {
-            routing: {
-              modelAttempts: [
-                {},
-                {
-                  providerAttempts: [
-                    { provider: 'anthropic' },
-                    {
-                      provider: 'vertex',
-                      credentialType: 'byok',
-                      success: false,
-                      statusCode: 404,
-                    },
-                  ],
-                },
-              ],
-            },
-          },
-        },
-      },
-      { status: 404 }
-    );
-
-    const result = await makeErrorReadable({
-      providerId: 'vercel',
-      requestedModel: 'google/gemini-3.5-flash',
-      request,
-      response,
-      isUserByok: true,
-    });
-
-    expect((await result?.json()).error_type).toBe('byok_error');
-  });
-
-  it('does not use the Vertex model hint when another attempt produced the 404', async () => {
-    const response = Response.json(
-      {
-        providerMetadata: {
-          gateway: {
-            routing: {
-              modelAttempts: [
-                {
-                  providerAttempts: [
-                    {
-                      provider: 'vertexAnthropic',
-                      credentialType: 'byok',
-                      success: false,
-                      statusCode: 403,
-                    },
-                    {
-                      provider: 'anthropic',
-                      credentialType: 'system',
-                      success: false,
-                      statusCode: 404,
-                    },
-                  ],
-                },
-              ],
-            },
-          },
-        },
-      },
-      { status: 404 }
-    );
+  it('does not label other user BYOK 404 responses as Vertex errors', async () => {
+    const response = Response.json({ error: { message: 'Model not found' } }, { status: 404 });
 
     await expect(
       makeErrorReadable({
diff --git a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
index 5f6edebff2..26476137a4 100644
--- a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
+++ b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
@@ -203,58 +203,8 @@ function byokErrorMessage(status: number): string | undefined {
   return byokErrorMessages[status];
 }
 
-const vercelVertexByokErrorSchema = z.object({
-  providerMetadata: z.object({
-    gateway: z.object({
-      routing: z.object({
-        modelAttempts: z.array(
-          z.object({
-            providerAttempts: z
-              .array(
-                z.object({
-                  provider: z.string().optional(),
-                  credentialType: z.string().optional(),
-                  success: z.boolean().optional(),
-                  statusCode: z.number().optional(),
-                })
-              )
-              .optional(),
-          })
-        ),
-      }),
-    }),
-  }),
-});
-
-async function vertexByokModelNotFoundResponse(
-  providerId: ProviderId,
-  response: Response,
-  isUserByok: boolean
-) {
-  if (providerId !== 'vercel' || !isUserByok || response.status !== 404) return undefined;
-
-  let body: unknown;
-  try {
-    body = await response.clone().json();
-  } catch {
-    return undefined;
-  }
-
-  const parsedBody = vercelVertexByokErrorSchema.safeParse(body);
-  if (!parsedBody.success) return undefined;
-
-  const hasVertexByokAttempt = parsedBody.data.providerMetadata.gateway.routing.modelAttempts.some(
-    modelAttempt =>
-      modelAttempt.providerAttempts?.some(
-        providerAttempt =>
-          (providerAttempt.provider === 'vertex' ||
-            providerAttempt.provider === 'vertexAnthropic') &&
-          providerAttempt.credentialType === 'byok' &&
-          providerAttempt.success === false &&
-          providerAttempt.statusCode === 404
-      ) === true
-  );
-  if (!hasVertexByokAttempt) return undefined;
+function vertexByokModelNotFoundResponse(response: Response, hasVertexUserByok: boolean) {
+  if (!hasVertexUserByok || response.status !== 404) return undefined;
 
   const error =
     '[BYOK] Google Vertex AI could not find the requested model. The model might not be enabled for your Google Cloud project or selected Vertex location.';
@@ -314,22 +264,20 @@ export async function makeErrorReadable({
   request,
   response,
   isUserByok,
+  hasVertexUserByok = false,
 }: {
   providerId: ProviderId;
   requestedModel: string;
   request: GatewayRequest;
   response: Response;
   isUserByok: boolean;
+  hasVertexUserByok?: boolean;
 }) {
   if (response.status < 400) {
     return undefined;
   }
 
-  const vertexByokResponse = await vertexByokModelNotFoundResponse(
-    providerId,
-    response,
-    isUserByok
-  );
+  const vertexByokResponse = vertexByokModelNotFoundResponse(response, hasVertexUserByok);
   if (vertexByokResponse) return vertexByokResponse;
 
   if (isUserByok) {

From edff44dca89bcdafe4f4c241b52bde0783c34f91 Mon Sep 17 00:00:00 2001
From: Christiaan Arnoldus <christiaan.arnoldus@outlook.com>
Date: Fri, 21 Aug 2026 15:56:40 +0200
Subject: [PATCH 09/12] refactor(ai-gateway): pass BYOK provider ids to errors

---
 .../src/app/api/openrouter/[...path]/route.ts |  4 +-
 .../lib/ai-gateway/llm-proxy-helpers.test.ts  | 50 +++++++++++++++----
 .../src/lib/ai-gateway/llm-proxy-helpers.ts   | 18 ++++---
 3 files changed, 50 insertions(+), 22 deletions(-)

diff --git a/apps/web/src/app/api/openrouter/[...path]/route.ts b/apps/web/src/app/api/openrouter/[...path]/route.ts
index de5f871ddd..fb5512ea62 100644
--- a/apps/web/src/app/api/openrouter/[...path]/route.ts
+++ b/apps/web/src/app/api/openrouter/[...path]/route.ts
@@ -1103,9 +1103,7 @@ export async function POST(request: NextRequest): Promise<NextResponseType<unkno
       requestedModel: effectiveModelIdLowerCased,
       request: requestBodyParsed,
       response,
-      isUserByok: !!effectiveProviderContext.userByok,
-      hasVertexUserByok:
-        effectiveProviderContext.userByok?.some(byok => byok.providerId === 'vertex') ?? false,
+      userByokProviderIds: effectiveProviderContext.userByok?.map(byok => byok.providerId) ?? null,
     });
     if (errorResponse) {
       await logUnrewrittenResponse({
diff --git a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
index c6b669e73c..273a745779 100644
--- a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
+++ b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
@@ -872,7 +872,7 @@ describe('makeErrorReadable', () => {
       requestedModel: 'anything',
       request,
       response,
-      isUserByok: false,
+      userByokProviderIds: null,
     });
     expect(result).toBeUndefined();
   });
@@ -885,8 +885,7 @@ describe('makeErrorReadable', () => {
       requestedModel: 'anthropic/claude-sonnet-5',
       request,
       response,
-      isUserByok: true,
-      hasVertexUserByok: true,
+      userByokProviderIds: ['vertex'],
     });
 
     expect(result?.status).toBe(404);
@@ -908,7 +907,36 @@ describe('makeErrorReadable', () => {
         requestedModel: 'anthropic/claude-sonnet-5',
         request,
         response,
-        isUserByok: true,
+        userByokProviderIds: ['anthropic'],
+      })
+    ).resolves.toBeUndefined();
+  });
+
+  it.each([
+    [401, []],
+    [402, ['anthropic']],
+    [403, []],
+    [429, ['anthropic']],
+  ] as const)('treats a non-null provider set as user BYOK for status %i', async (status, ids) => {
+    const result = await makeErrorReadable({
+      providerId: 'vercel',
+      requestedModel: 'anthropic/claude-sonnet-5',
+      request,
+      response: Response.json({}, { status }),
+      userByokProviderIds: [...ids],
+    });
+
+    expect((await result?.json()).error_type).toBe('byok_error');
+  });
+
+  it('does not use generic BYOK errors for a null provider set', async () => {
+    await expect(
+      makeErrorReadable({
+        providerId: 'vercel',
+        requestedModel: 'anthropic/claude-sonnet-5',
+        request,
+        response: Response.json({}, { status: 401 }),
+        userByokProviderIds: null,
       })
     ).resolves.toBeUndefined();
   });
@@ -931,7 +959,7 @@ describe('makeErrorReadable', () => {
       requestedModel: 'qwen/qwen3.7-plus',
       request,
       response,
-      isUserByok: false,
+      userByokProviderIds: null,
     });
 
     expect(result?.status).toBe(404);
@@ -963,7 +991,7 @@ describe('makeErrorReadable', () => {
       requestedModel: 'qwen/qwen3.7-plus',
       request,
       response,
-      isUserByok: false,
+      userByokProviderIds: null,
     });
 
     expect(result).toBeDefined();
@@ -991,7 +1019,7 @@ describe('makeErrorReadable', () => {
         requestedModel: 'anything',
         request,
         response,
-        isUserByok: false,
+        userByokProviderIds: null,
       })
     ).resolves.toBeUndefined();
   });
@@ -1017,7 +1045,7 @@ describe('makeErrorReadable', () => {
           requestedModel: 'anything',
           request,
           response,
-          isUserByok: false,
+          userByokProviderIds: null,
         })
       ).resolves.toBeUndefined();
     }
@@ -1034,7 +1062,7 @@ describe('makeErrorReadable', () => {
       requestedModel: 'kilo-internal/custom-endpoint',
       request,
       response,
-      isUserByok: false,
+      userByokProviderIds: null,
     });
 
     expect(result).toBeUndefined();
@@ -1051,7 +1079,7 @@ describe('makeErrorReadable', () => {
       requestedModel: 'experiment/test-model',
       request,
       response,
-      isUserByok: false,
+      userByokProviderIds: null,
     });
 
     expect(result).toBeDefined();
@@ -1074,7 +1102,7 @@ describe('makeErrorReadable', () => {
       requestedModel: 'stealth/claude-opus-4.7',
       request,
       response,
-      isUserByok: false,
+      userByokProviderIds: null,
     });
 
     expect(result).toBeDefined();
diff --git a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
index 26476137a4..1775b917a9 100644
--- a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
+++ b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
@@ -47,6 +47,7 @@ import { computeOpenRouterCostFields } from '@/lib/ai-gateway/processUsage.share
 import { persistExperimentAttribution } from '@/lib/ai-gateway/experiments/persist';
 import { ProxyErrorType } from '@/lib/proxy-error-types';
 import { getInferenceProvider } from '@/lib/ai-gateway/providers/kilo-exclusive-model';
+import type { UserByokProviderId } from '@/lib/ai-gateway/providers/openrouter/inference-provider-id';
 
 // FIM suffix markers for tracking purposes - used to wrap suffix in a fake system prompt format
 // This allows FIM requests to be tracked consistently with chat requests
@@ -203,8 +204,11 @@ function byokErrorMessage(status: number): string | undefined {
   return byokErrorMessages[status];
 }
 
-function vertexByokModelNotFoundResponse(response: Response, hasVertexUserByok: boolean) {
-  if (!hasVertexUserByok || response.status !== 404) return undefined;
+function vertexByokModelNotFoundResponse(
+  response: Response,
+  userByokProviderIds: UserByokProviderId[] | null
+) {
+  if (!userByokProviderIds?.includes('vertex') || response.status !== 404) return undefined;
 
   const error =
     '[BYOK] Google Vertex AI could not find the requested model. The model might not be enabled for your Google Cloud project or selected Vertex location.';
@@ -263,24 +267,22 @@ export async function makeErrorReadable({
   requestedModel,
   request,
   response,
-  isUserByok,
-  hasVertexUserByok = false,
+  userByokProviderIds,
 }: {
   providerId: ProviderId;
   requestedModel: string;
   request: GatewayRequest;
   response: Response;
-  isUserByok: boolean;
-  hasVertexUserByok?: boolean;
+  userByokProviderIds: UserByokProviderId[] | null;
 }) {
   if (response.status < 400) {
     return undefined;
   }
 
-  const vertexByokResponse = vertexByokModelNotFoundResponse(response, hasVertexUserByok);
+  const vertexByokResponse = vertexByokModelNotFoundResponse(response, userByokProviderIds);
   if (vertexByokResponse) return vertexByokResponse;
 
-  if (isUserByok) {
+  if (userByokProviderIds !== null) {
     const byokMessage = byokErrorMessage(response.status);
     if (byokMessage) {
       warnExceptInTest(`Responding with ${response.status} ${byokMessage}`);

From 4c3ecf0680b78e01edc580b3456223fd1abc3a58 Mon Sep 17 00:00:00 2001
From: Christiaan Arnoldus <christiaan.arnoldus@outlook.com>
Date: Fri, 21 Aug 2026 16:15:35 +0200
Subject: [PATCH 10/12] fix(ai-gateway): narrow Vertex provider ids explicitly

---
 apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
index 1775b917a9..3ac9529bb9 100644
--- a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
+++ b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.ts
@@ -208,7 +208,13 @@ function vertexByokModelNotFoundResponse(
   response: Response,
   userByokProviderIds: UserByokProviderId[] | null
 ) {
-  if (!userByokProviderIds?.includes('vertex') || response.status !== 404) return undefined;
+  if (
+    userByokProviderIds === null ||
+    !userByokProviderIds.includes('vertex') ||
+    response.status !== 404
+  ) {
+    return undefined;
+  }
 
   const error =
     '[BYOK] Google Vertex AI could not find the requested model. The model might not be enabled for your Google Cloud project or selected Vertex location.';

From 86451382921da623d27a51be42872bacc5b87378 Mon Sep 17 00:00:00 2001
From: Christiaan Arnoldus <christiaan.arnoldus@outlook.com>
Date: Fri, 21 Aug 2026 16:19:39 +0200
Subject: [PATCH 11/12] fix(ai-gateway): narrow BYOK context explicitly

---
 apps/web/src/app/api/openrouter/[...path]/route.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/app/api/openrouter/[...path]/route.ts b/apps/web/src/app/api/openrouter/[...path]/route.ts
index fb5512ea62..4d83617e9f 100644
--- a/apps/web/src/app/api/openrouter/[...path]/route.ts
+++ b/apps/web/src/app/api/openrouter/[...path]/route.ts
@@ -1103,7 +1103,10 @@ export async function POST(request: NextRequest): Promise<NextResponseType<unkno
       requestedModel: effectiveModelIdLowerCased,
       request: requestBodyParsed,
       response,
-      userByokProviderIds: effectiveProviderContext.userByok?.map(byok => byok.providerId) ?? null,
+      userByokProviderIds:
+        effectiveProviderContext.userByok === null
+          ? null
+          : effectiveProviderContext.userByok.map(byok => byok.providerId),
     });
     if (errorResponse) {
       await logUnrewrittenResponse({

From 2bad376e041c0e72e8c552d155f65bc041db44fb Mon Sep 17 00:00:00 2001
From: Christiaan Arnoldus <christiaan.arnoldus@outlook.com>
Date: Fri, 21 Aug 2026 16:25:42 +0200
Subject: [PATCH 12/12] test(ai-gateway): guard BYOK error response

---
 apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
index 273a745779..64274da1c1 100644
--- a/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
+++ b/apps/web/src/lib/ai-gateway/llm-proxy-helpers.test.ts
@@ -926,7 +926,9 @@ describe('makeErrorReadable', () => {
       userByokProviderIds: [...ids],
     });
 
-    expect((await result?.json()).error_type).toBe('byok_error');
+    expect(result).toBeDefined();
+    if (!result) throw new Error('Expected a readable BYOK error response');
+    expect((await result.json()).error_type).toBe('byok_error');
   });
 
   it('does not use generic BYOK errors for a null provider set', async () => {