pi-provider-litellm 4.2.0 → 4.3.1

package/src/index.ts

@@ -20,9 +20,23 @@ import * as piCodingAgent from "@earendil-works/pi-coding-agent";
 import { getAgentDir, readStoredCredential } from "@earendil-works/pi-coding-agent";
 import { budgetDisplaySetting, setupLiteLLMBudget } from "./budget.js";
 import { setupLiteLLMCostTracking } from "./cost.js";
-import { discoverModels, isGpt6OrNewerModel, isGpt55OrNewerModel, normalizeBaseUrl } from "./discover.js";
+import {
+  discoverModels,
+  isGpt6OrNewerModel,
+  isGpt55OrNewerModel,
+  normalizeBaseUrl,
+  trimTrailingSlashes,
+} from "./discover.js";
 import { getGcloudToken, hasGcloudAdcCredentials, isGcloudTokenAuthEnabled } from "./gcloud-token.js";
-import { createLiteLLMProvider, DEFAULT_LITELLM_BASE_URL, isPlaceholderHost, toNativeModels } from "./provider.js";
+import type { LiteLLMImageModel } from "./images.js";
+import { readStoredModels } from "./models-store.js";
+import {
+  createLiteLLMProvider,
+  DEFAULT_LITELLM_BASE_URL,
+  isPlaceholderHost,
+  toNativeImageModels,
+  toNativeModels,
+} from "./provider.js";
 import { parseProxyVersion, proxyVersionAtLeast } from "./proxy-version.js";
 import { createSkillsPromptSection, createSkillToolDefinitions, listSkills } from "./skills.js";
 import type {
@@ -36,9 +50,13 @@ import type {
 
 const PROVIDER_NAME = "litellm";
 const SETTINGS_KEY = "litellm";
+const SETTINGS_FILENAME = "settings.json";
+const MODELS_FILENAME = "models.json";
 const ENV_BASE_URL = "LITELLM_BASE_URL";
 const ENV_API_KEY = "LITELLM_API_KEY";
 const ENV_DISPLAY_NAME = "LITELLM_DISPLAY_NAME";
+const ENV_PROVIDERS = "LITELLM_PROVIDERS";
+const ENV_PROVIDERS_JSON = "LITELLM_PROVIDERS_JSON";
 const GCLOUD_ADC_SOURCE = "gcloud ADC";
 const ENV_API_KEY_HELPER = "LITELLM_API_KEY_HELPER";
 const ENV_HEADERS = "LITELLM_HEADERS";
@@ -72,10 +90,14 @@ type RawProviderSettings = {
   headers?: unknown;
   enabled?: unknown;
   allowInsecureHttp?: unknown;
+  useGcloudTokenAuth?: unknown;
+  enableOAuth?: unknown;
   oidc?: unknown;
+  enableMcp?: unknown;
+  mcp?: unknown;
 };
 
-type ProviderDefinition = {
+export type ProviderDefinition = {
   name: string;
   displayName: string;
   baseUrl?: string;
@@ -87,16 +109,152 @@ type ProviderDefinition = {
   allowInsecureHttp: boolean;
   /** Raw `oidc` setting, validated at login so a bad value never breaks startup. */
   oidc?: unknown;
+  envPrefix?: string;
+  enableMcp?: boolean;
 };
 
+const RESERVED_PROVIDER_NAMES = new Set(["mcp", "skills", "codemode", "tool_search", "litellm"]);
+const PROVIDER_NAME_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const PROVIDER_ENV_VAR_REGEX =
+  /^LITELLM_PROVIDER_([A-Z0-9_]+?)_(BASE_URL|API_KEY_HELPER|API_KEY|HEADERS|DISPLAY_NAME|NAME|ALLOW_INSECURE_HTTP|USE_GCLOUD_AUTH|ENABLE_OAUTH|ENABLE_MCP|MCP_ENABLED)$/;
+
+export function isValidProviderName(name: string): boolean {
+  if (typeof name !== "string") return false;
+  if (!PROVIDER_NAME_REGEX.test(name)) return false;
+  if (RESERVED_PROVIDER_NAMES.has(name)) return false;
+  return true;
+}
+
+export function parseCanonicalProviderList(raw: string | undefined): string[] {
+  if (typeof raw !== "string") return [];
+  const trimmed = raw.trim();
+  if (!trimmed) return [];
+  return trimmed
+    .split(/[\s,]+/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function parseProvidersJson(raw: string | undefined): Record<string, RawProviderSettings> | undefined {
+  if (typeof raw !== "string") return undefined;
+  const trimmed = raw.trim();
+  if (!trimmed) return undefined;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (!isPlainObject(parsed)) return undefined;
+    const result: Record<string, RawProviderSettings> = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (isPlainObject(value)) {
+        result[key] = value as RawProviderSettings;
+      }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function parseBooleanSetting(value: unknown): boolean {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    const trimmed = value.trim().toLowerCase();
+    return trimmed === "1" || trimmed === "true";
+  }
+  return false;
+}
+
+export type ParsedProviderEnv = {
+  token: string;
+  envPrefix: string;
+  name?: string;
+  displayName?: string;
+  baseUrl?: string;
+  apiKey?: string;
+  apiKeyHelper?: string;
+  headers?: unknown;
+  allowInsecureHttp?: boolean;
+  useGcloudTokenAuth?: boolean;
+  enableOAuth?: boolean;
+  enableMcp?: boolean;
+};
+
+export function parseProviderEnvVars(env: NodeJS.ProcessEnv): Record<string, ParsedProviderEnv> {
+  const result: Record<string, ParsedProviderEnv> = {};
+  for (const key of Object.keys(env)) {
+    const match = key.match(PROVIDER_ENV_VAR_REGEX);
+    if (!match) continue;
+    const token = match[1]!;
+    const field = match[2]!;
+    const val = env[key];
+    if (val === undefined) continue;
+
+    if (!result[token]) {
+      result[token] = {
+        token,
+        envPrefix: `LITELLM_PROVIDER_${token}`,
+      };
+    }
+    const entry = result[token]!;
+    switch (field) {
+      case "BASE_URL":
+        entry.baseUrl = cleanConfig(val);
+        break;
+      case "API_KEY":
+        entry.apiKey = cleanConfig(val);
+        break;
+      case "API_KEY_HELPER":
+        entry.apiKeyHelper = cleanConfig(val);
+        break;
+      case "HEADERS":
+        entry.headers = cleanConfig(val);
+        break;
+      case "DISPLAY_NAME":
+        entry.displayName = cleanConfig(val);
+        break;
+      case "NAME":
+        entry.name = cleanConfig(val);
+        break;
+      case "ALLOW_INSECURE_HTTP":
+        entry.allowInsecureHttp = parseBooleanSetting(val);
+        break;
+      case "USE_GCLOUD_AUTH":
+        entry.useGcloudTokenAuth = parseBooleanSetting(val);
+        break;
+      case "ENABLE_OAUTH":
+        entry.enableOAuth = parseBooleanSetting(val);
+        break;
+      case "ENABLE_MCP":
+      case "MCP_ENABLED":
+        entry.enableMcp = parseBooleanSetting(val);
+        break;
+    }
+  }
+  return result;
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+/** Remove a leading UTF-8 byte order mark, as Pi's own `stripBom` does. */
+function stripBom(content: string): string {
+  return content.startsWith("\uFEFF") ? content.slice(1) : content;
+}
+
+/** Pi's `stripJsonComments`, mirrored so a file Pi accepts is never silently ignored here. */
+function stripJsonComments(input: string): string {
+  return input
+    .replace(/"(?:\\.|[^"\\])*"|\/\/[^\n]*/g, (match) => (match[0] === '"' ? match : ""))
+    .replace(
+      /"(?:\\.|[^"\\])*"|,(\s*[}\]])/g,
+      (match, tail: string | undefined) => tail ?? (match[0] === '"' ? match : ""),
+    );
+}
+
 async function readGlobalLiteLLMSettings(): Promise<Record<string, unknown> | undefined> {
   try {
-    const raw = await readFile(join(getAgentDir(), "settings.json"), "utf8");
-    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const raw = await readFile(join(getAgentDir(), SETTINGS_FILENAME), "utf8");
+    const parsed = JSON.parse(stripBom(raw)) as Record<string, unknown>;
     const settings = parsed[SETTINGS_KEY];
     return settings && typeof settings === "object" && !Array.isArray(settings)
       ? (settings as Record<string, unknown>)
@@ -106,6 +264,45 @@ async function readGlobalLiteLLMSettings(): Promise<Record<string, unknown> | un
   }
 }
 
+// Pi's own provider file. Only `providers` is read: `skills`/`mcp`/`budget` stay settings.json-only,
+// so a provider block here cannot switch a feature off. Aliases mirror settings.json's shape, and
+// the native `providers.litellm` slot wins when a file sets both. Global agent dir only.
+async function readModelsProviderSettings(): Promise<Record<string, unknown> | undefined> {
+  try {
+    // models.json is JSONC, unlike settings.json; a strict parse would drop a config Pi accepts.
+    const raw = await readFile(join(getAgentDir(), MODELS_FILENAME), "utf8");
+    const parsed = JSON.parse(stripJsonComments(stripBom(raw))) as Record<string, unknown>;
+    const providers: Record<string, unknown> = {};
+    const aliases = isPlainObject(parsed[SETTINGS_KEY]) ? parsed[SETTINGS_KEY].providers : undefined;
+    if (isPlainObject(aliases)) Object.assign(providers, aliases);
+    const native = isPlainObject(parsed.providers) ? parsed.providers[PROVIDER_NAME] : undefined;
+    if (isPlainObject(native)) {
+      const existing = providers[PROVIDER_NAME];
+      providers[PROVIDER_NAME] = isPlainObject(existing) ? { ...existing, ...native } : native;
+    }
+    return Object.keys(providers).length > 0 ? { providers } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// A provider block may live in either file; merge per field with models.json winning. Non-provider
+// settings.json keys pass through untouched, which is what keeps `skills`/`mcp`/`budget` working.
+function mergeProviderSettings(
+  settings: Record<string, unknown> | undefined,
+  models: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  const modelsProviders = isPlainObject(models?.providers) ? models.providers : undefined;
+  if (!modelsProviders) return settings;
+  const settingsProviders = isPlainObject(settings?.providers) ? settings.providers : undefined;
+  const providers: Record<string, unknown> = { ...settingsProviders };
+  for (const [name, raw] of Object.entries(modelsProviders)) {
+    const base = settingsProviders?.[name];
+    providers[name] = isPlainObject(base) && isPlainObject(raw) ? { ...base, ...raw } : raw;
+  }
+  return { ...settings, providers };
+}
+
 function cleanConfig(raw: string | undefined): string | undefined {
   const trimmed = raw?.trim();
   return trimmed && trimmed !== "undefined" ? trimmed : undefined;
@@ -126,6 +323,7 @@ function resolveCredentialRoot(
     credentialBaseUrl ??
     cleanConfig(requestBaseUrl) ??
     cleanConfig(definition.baseUrl) ??
+    (definition.envPrefix ? cleanConfig(process.env[`${definition.envPrefix}_BASE_URL`]) : undefined) ??
     (definition.useDefaultEnv ? cleanConfig(process.env[ENV_BASE_URL]) : undefined);
   return baseUrl ? normalizeBaseUrl(baseUrl, definition.allowInsecureHttp) : undefined;
 }
@@ -376,28 +574,38 @@ function parseCustomHeaders(raw: string | undefined): Record<string, string> | u
 }
 
 function resolveHeaders(definition: ProviderDefinition): Record<string, string> | undefined {
-  if (typeof definition.headers === "string") return parseCustomHeaders(resolveTemplateConfigValue(definition.headers));
-  return parseHeaderRecord(definition.headers);
+  const rawHeaders =
+    definition.headers ??
+    (definition.envPrefix ? process.env[`${definition.envPrefix}_HEADERS`] : undefined) ??
+    (definition.useDefaultEnv ? process.env[ENV_HEADERS] : undefined);
+  if (typeof rawHeaders === "string") return parseCustomHeaders(resolveTemplateConfigValue(rawHeaders));
+  return parseHeaderRecord(rawHeaders);
 }
 
 async function resolveHeadersFromContext(
   definition: ProviderDefinition,
   env: (name: string) => Promise<string | undefined>,
 ): Promise<Record<string, string> | undefined> {
-  if (typeof definition.headers === "string")
-    return parseCustomHeaders(await resolveTemplateConfigValueFromContext(definition.headers, env));
-  return parseHeaderRecord(definition.headers);
+  const rawHeaders =
+    definition.headers ??
+    (definition.envPrefix ? await env(`${definition.envPrefix}_HEADERS`) : undefined) ??
+    (definition.useDefaultEnv ? await env(ENV_HEADERS) : undefined);
+  if (typeof rawHeaders === "string")
+    return parseCustomHeaders(await resolveTemplateConfigValueFromContext(rawHeaders, env));
+  return parseHeaderRecord(rawHeaders);
 }
 
-async function resolveCredentials(
+export async function resolveCredentials(
   definition: ProviderDefinition,
   { executeHelpers = true } = {},
 ): Promise<ResolvedCredentials> {
   const configuredBase =
-    cleanConfig(definition.baseUrl) ?? (definition.useDefaultEnv ? cleanConfig(process.env[ENV_BASE_URL]) : undefined);
-  const envKey = definition.useDefaultEnv ? cleanConfig(process.env[ENV_API_KEY]) : undefined;
-  const envHelperCommand = definition.useDefaultEnv ? getApiKeyHelperCommand() : undefined;
-  const useGcloudToken = definition.useGcloudTokenAuth && isGcloudTokenAuthEnabled();
+    cleanConfig(definition.baseUrl) ??
+    (definition.envPrefix ? cleanConfig(process.env[`${definition.envPrefix}_BASE_URL`]) : undefined) ??
+    (definition.useDefaultEnv ? cleanConfig(process.env[ENV_BASE_URL]) : undefined);
+  const useGcloudToken = definition.useDefaultEnv
+    ? definition.useGcloudTokenAuth && isGcloudTokenAuthEnabled()
+    : definition.useGcloudTokenAuth;
   const gcloudKey = executeHelpers && useGcloudToken ? (await getGcloudToken())?.trim() : undefined;
   // Resolved lazily so a `!command` key is not executed when a
   // higher-precedence credential (saved auth, gcloud token) already won.
@@ -408,10 +616,34 @@ async function resolveCredentials(
       warnUnresolvedApiKeyConfig(definition.name, definition.apiKeyConfig);
     }
   }
-  const helperKey =
-    !gcloudKey && !configuredKey && executeHelpers && envHelperCommand
-      ? executeApiKeyCommand(envHelperCommand)
-      : undefined;
+
+  let helperKey: string | undefined;
+  let helperCommand: string | undefined;
+  let envKey: string | undefined;
+  let envKeySource: string | undefined;
+
+  if (!gcloudKey && !configuredKey && definition.envPrefix) {
+    helperCommand = normalizeCommand(process.env[`${definition.envPrefix}_API_KEY_HELPER`]);
+    if (helperCommand && executeHelpers) {
+      helperKey = executeApiKeyCommand(helperCommand);
+    }
+    if (!helperCommand) {
+      envKey = cleanConfig(process.env[`${definition.envPrefix}_API_KEY`]);
+      if (envKey) envKeySource = `$${definition.envPrefix}_API_KEY`;
+    }
+  }
+
+  if (!gcloudKey && !configuredKey && !helperKey && !helperCommand && !envKey && definition.useDefaultEnv) {
+    helperCommand = getApiKeyHelperCommand();
+    if (helperCommand && executeHelpers) {
+      helperKey = executeApiKeyCommand(helperCommand);
+    }
+    if (!helperCommand) {
+      envKey = cleanConfig(process.env[ENV_API_KEY]);
+      if (envKey) envKeySource = `$${ENV_API_KEY}`;
+    }
+  }
+
   const apiKey = gcloudKey || configuredKey || helperKey || envKey;
 
   let apiKeyConfig: string | undefined;
@@ -419,12 +651,12 @@ async function resolveCredentials(
     apiKeyConfig = definition.apiKeyConfig;
   } else if (!executeHelpers && definition.apiKeyConfig?.startsWith("!")) {
     apiKeyConfig = definition.apiKeyConfig;
-  } else if (helperKey && envHelperCommand) {
-    apiKeyConfig = envHelperCommand;
-  } else if (!executeHelpers && envHelperCommand) {
-    apiKeyConfig = envHelperCommand;
+  } else if (helperKey && helperCommand) {
+    apiKeyConfig = helperCommand;
+  } else if (!executeHelpers && helperCommand) {
+    apiKeyConfig = helperCommand;
   } else if (envKey) {
-    apiKeyConfig = `$${ENV_API_KEY}`;
+    apiKeyConfig = envKeySource;
   }
   return {
     baseUrl: configuredBase ? normalizeBaseUrl(configuredBase, definition.allowInsecureHttp) : undefined,
@@ -486,7 +718,20 @@ function normalizeProviderSettings(raw: unknown): RawProviderSettings | undefine
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
   const record = raw as RawProviderSettings;
   if (record.enabled === false) return undefined;
-  return record;
+  const enableMcp =
+    record.enableMcp !== undefined
+      ? parseBooleanSetting(record.enableMcp)
+      : isPlainObject(record.mcp)
+        ? record.mcp.enabled !== undefined
+          ? parseBooleanSetting(record.mcp.enabled)
+          : undefined
+        : record.mcp !== undefined
+          ? parseBooleanSetting(record.mcp)
+          : undefined;
+  return {
+    ...record,
+    ...(enableMcp !== undefined ? { enableMcp } : {}),
+  };
 }
 
 function isFeatureEnabled(
@@ -497,35 +742,191 @@ function isFeatureEnabled(
   return !isPlainObject(raw) || raw.enabled !== false;
 }
 
-function getProviderDefinitions(settings: Record<string, unknown> | undefined): ProviderDefinition[] {
+type IntermediateProvider = {
+  name: string;
+  displayName?: string;
+  baseUrl?: string;
+  apiKeyConfig?: string;
+  headers?: unknown;
+  allowInsecureHttp?: boolean;
+  useGcloudTokenAuth?: boolean;
+  enableOAuth?: boolean;
+  envPrefix?: string;
+  enableMcp?: boolean;
+};
+
+export function getProviderDefinitions(settings: Record<string, unknown> | undefined): ProviderDefinition[] {
   const rawProviders = settings?.providers && typeof settings.providers === "object" ? settings.providers : undefined;
   const providerSettings = rawProviders as Record<string, unknown> | undefined;
   const defaultSettings = normalizeProviderSettings(providerSettings?.[PROVIDER_NAME]);
   const defaultDisplayName = cleanConfig(process.env[ENV_DISPLAY_NAME]) ?? "LiteLLM";
+  const parsedEnv = parseProviderEnvVars(process.env);
+  const primaryEnv = parsedEnv[PROVIDER_NAME.toUpperCase()];
+
+  const primaryDefinition: ProviderDefinition = {
+    name: PROVIDER_NAME,
+    displayName: stringSetting(defaultSettings?.displayName) ?? defaultDisplayName,
+    baseUrl: stringSetting(defaultSettings?.baseUrl),
+    apiKeyConfig: stringSetting(defaultSettings?.apiKey),
+    headers: defaultSettings?.headers ?? `$${ENV_HEADERS}`,
+    useDefaultEnv: true,
+    useGcloudTokenAuth: true,
+    enableOAuth: true,
+    allowInsecureHttp: defaultSettings?.allowInsecureHttp === true,
+    oidc: defaultSettings?.oidc,
+    enableMcp: typeof defaultSettings?.enableMcp === "boolean" ? defaultSettings.enableMcp : primaryEnv?.enableMcp,
+  };
 
-  const makeDefinition = (
-    name: string,
-    raw: RawProviderSettings | undefined,
-    isDefault: boolean,
-  ): ProviderDefinition => ({
-    name,
-    displayName: stringSetting(raw?.displayName) ?? (isDefault ? defaultDisplayName : name),
-    baseUrl: stringSetting(raw?.baseUrl),
-    apiKeyConfig: stringSetting(raw?.apiKey),
-    headers: raw?.headers ?? (isDefault ? `$${ENV_HEADERS}` : undefined),
-    useDefaultEnv: isDefault,
-    useGcloudTokenAuth: isDefault,
-    enableOAuth: isDefault,
-    allowInsecureHttp: raw?.allowInsecureHttp === true,
-    oidc: isDefault ? raw?.oidc : undefined,
-  });
+  const secondaryProviders = new Map<string, IntermediateProvider>();
+  const disabledProviders = new Set<string>();
+
+  // 1. Incorporate LITELLM_PROVIDERS_JSON
+  const jsonProviders = parseProvidersJson(process.env[ENV_PROVIDERS_JSON]);
+  if (jsonProviders) {
+    for (const [name, raw] of Object.entries(jsonProviders)) {
+      if (!isValidProviderName(name)) continue;
+      if (raw.enabled === false) {
+        disabledProviders.add(name);
+        continue;
+      }
+      const normalized = normalizeProviderSettings(raw);
+      if (!normalized) continue;
+      secondaryProviders.set(name, {
+        name,
+        displayName: stringSetting(normalized.displayName),
+        baseUrl: stringSetting(normalized.baseUrl),
+        apiKeyConfig: stringSetting(normalized.apiKey),
+        headers: normalized.headers,
+        allowInsecureHttp: parseBooleanSetting(normalized.allowInsecureHttp),
+        useGcloudTokenAuth: parseBooleanSetting(normalized.useGcloudTokenAuth),
+        enableOAuth: parseBooleanSetting(normalized.enableOAuth),
+        enableMcp: typeof normalized.enableMcp === "boolean" ? normalized.enableMcp : undefined,
+      });
+    }
+  }
+
+  // 2. Scan env vars
+  const claimedTokens = new Set<string>([PROVIDER_NAME.toUpperCase()]);
+
+  // 3. Declared IDs claim their env token before step 4 derives new IDs: LITELLM_PROVIDERS first, then JSON keys,
+  // then settings.json aliases that have scoped variables (step 5 still applies their settings on top)
+  const canonicalList = parseCanonicalProviderList(process.env[ENV_PROVIDERS]);
+  const settingsIds = Object.entries(providerSettings ?? {})
+    .filter(([name, raw]) => normalizeProviderSettings(raw) && parsedEnv[name.toUpperCase().replace(/-/g, "_")])
+    .map(([name]) => name);
+  const tokenOwners = new Map<string, string>([[PROVIDER_NAME.toUpperCase(), PROVIDER_NAME]]);
+  for (const canonicalId of new Set([...canonicalList, ...secondaryProviders.keys(), ...settingsIds])) {
+    if (!isValidProviderName(canonicalId)) continue;
+    if (disabledProviders.has(canonicalId)) continue;
+    const token = canonicalId.toUpperCase().replace(/-/g, "_");
+    const owner = tokenOwners.get(token);
+    const hasCollision = owner !== undefined && owner !== canonicalId;
+    if (!hasCollision && !tokenOwners.has(token)) {
+      tokenOwners.set(token, canonicalId);
+    }
+    const envData = !hasCollision ? parsedEnv[token] : undefined;
+    if (envData) claimedTokens.add(token);
+
+    const existing = secondaryProviders.get(canonicalId);
+    secondaryProviders.set(canonicalId, {
+      name: canonicalId,
+      displayName: envData?.displayName ?? existing?.displayName,
+      baseUrl: existing?.baseUrl,
+      apiKeyConfig: existing?.apiKeyConfig,
+      headers: existing?.headers,
+      allowInsecureHttp: envData?.allowInsecureHttp ?? existing?.allowInsecureHttp,
+      useGcloudTokenAuth: envData?.useGcloudTokenAuth ?? existing?.useGcloudTokenAuth,
+      enableOAuth: envData?.enableOAuth ?? existing?.enableOAuth,
+      envPrefix: envData?.envPrefix ?? existing?.envPrefix,
+      enableMcp: envData?.enableMcp ?? existing?.enableMcp,
+    });
+  }
+
+  // 4. Incorporate remaining unlisted prefix-scanned tokens
+  for (const [token, envData] of Object.entries(parsedEnv)) {
+    if (claimedTokens.has(token)) continue;
+    const providerId = envData.name ?? token.toLowerCase().replace(/_/g, "-");
+    if (!isValidProviderName(providerId)) continue;
+    if (disabledProviders.has(providerId) || disabledProviders.has(token.toLowerCase())) continue;
+
+    tokenOwners.set(token, providerId);
+
+    const existing = secondaryProviders.get(providerId);
+    secondaryProviders.set(providerId, {
+      name: providerId,
+      displayName: envData.displayName ?? existing?.displayName,
+      baseUrl: existing?.baseUrl,
+      apiKeyConfig: existing?.apiKeyConfig,
+      headers: existing?.headers,
+      allowInsecureHttp: envData.allowInsecureHttp ?? existing?.allowInsecureHttp,
+      useGcloudTokenAuth: envData.useGcloudTokenAuth ?? existing?.useGcloudTokenAuth,
+      enableOAuth: envData.enableOAuth ?? existing?.enableOAuth,
+      envPrefix: envData.envPrefix ?? existing?.envPrefix,
+      enableMcp: envData.enableMcp ?? existing?.enableMcp,
+    });
+  }
 
-  const definitions = [makeDefinition(PROVIDER_NAME, defaultSettings, true)];
+  // 5. Merge with settings.json (disk settings override env vars; enabled === false excludes)
   for (const [name, raw] of Object.entries(providerSettings ?? {})) {
     if (name === PROVIDER_NAME) continue;
-    const normalized = normalizeProviderSettings(raw);
-    if (!normalized) continue;
-    definitions.push(makeDefinition(name, normalized, false));
+    if (typeof name !== "string" || name.length === 0 || RESERVED_PROVIDER_NAMES.has(name)) continue;
+
+    const rawRecord = normalizeProviderSettings(raw);
+
+    if (!rawRecord) {
+      secondaryProviders.delete(name);
+      continue;
+    }
+
+    const existing = secondaryProviders.get(name);
+    const token = name.toUpperCase().replace(/-/g, "_");
+    let matchingEnvPrefix = existing ? existing.envPrefix : undefined;
+    if (!existing) {
+      const owner = tokenOwners.get(token);
+      if ((owner === undefined || owner === name) && !claimedTokens.has(token) && parsedEnv[token]) {
+        matchingEnvPrefix = `LITELLM_PROVIDER_${token}`;
+        tokenOwners.set(token, name);
+        claimedTokens.add(token);
+      }
+    }
+
+    secondaryProviders.set(name, {
+      name,
+      displayName: stringSetting(rawRecord.displayName) ?? existing?.displayName,
+      baseUrl: stringSetting(rawRecord.baseUrl) ?? existing?.baseUrl,
+      apiKeyConfig: stringSetting(rawRecord.apiKey) ?? existing?.apiKeyConfig,
+      headers: rawRecord.headers ?? existing?.headers,
+      allowInsecureHttp:
+        typeof rawRecord.allowInsecureHttp === "boolean"
+          ? rawRecord.allowInsecureHttp
+          : (existing?.allowInsecureHttp ?? false),
+      useGcloudTokenAuth:
+        typeof rawRecord.useGcloudTokenAuth === "boolean"
+          ? rawRecord.useGcloudTokenAuth
+          : (existing?.useGcloudTokenAuth ?? false),
+      enableOAuth:
+        typeof rawRecord.enableOAuth === "boolean" ? rawRecord.enableOAuth : (existing?.enableOAuth ?? false),
+      envPrefix: matchingEnvPrefix,
+      enableMcp: typeof rawRecord.enableMcp === "boolean" ? rawRecord.enableMcp : existing?.enableMcp,
+    });
+  }
+
+  const definitions: ProviderDefinition[] = [primaryDefinition];
+  for (const [name, entry] of secondaryProviders) {
+    definitions.push({
+      name,
+      displayName: entry.displayName ?? name,
+      baseUrl: entry.baseUrl,
+      apiKeyConfig: entry.apiKeyConfig,
+      headers: entry.headers,
+      useDefaultEnv: false,
+      useGcloudTokenAuth: entry.useGcloudTokenAuth ?? false,
+      enableOAuth: entry.enableOAuth ?? false,
+      allowInsecureHttp: entry.allowInsecureHttp ?? false,
+      oidc: undefined,
+      envPrefix: entry.envPrefix,
+      enableMcp: entry.enableMcp,
+    });
   }
   return definitions;
 }
@@ -541,6 +942,10 @@ function knownBaseUrl(definition: ProviderDefinition): { url: string; source: st
   const stored = readStoredCredential(definition.name, join(getAgentDir(), "auth.json"));
   const candidates: [string | undefined, string][] = [
     [cleanConfig(definition.baseUrl), "configured"],
+    [
+      definition.envPrefix ? cleanConfig(process.env[`${definition.envPrefix}_BASE_URL`]) : undefined,
+      `$${definition.envPrefix}_BASE_URL`,
+    ],
     [definition.useDefaultEnv ? cleanConfig(process.env[ENV_BASE_URL]) : undefined, `$${ENV_BASE_URL}`],
     [
       stored?.type === "oauth"
@@ -634,7 +1039,7 @@ function authRequestHeaders(headers?: Record<string, string>, contentType?: stri
 function canonicalIssuer(value: string): string {
   const url = new URL(value);
   if (url.username || url.password || url.search || url.hash) throw new Error("LiteLLM CLI auth has invalid issuer");
-  return `${url.origin}${url.pathname.replace(/\/+$/, "") || "/"}`;
+  return `${url.origin}${trimTrailingSlashes(url.pathname) || "/"}`;
 }
 
 function sameOriginUrl(value: unknown, issuer: URL, field: string): string {
@@ -993,6 +1398,7 @@ type OidcCredentials = OAuthCredentials & {
   clientId: string;
   tokenEndpoint: string;
   subject: string;
+  scope: string;
 };
 
 type OidcTokenResult =
@@ -1031,15 +1437,18 @@ function parseOidcConfig(raw: unknown): OidcConfig {
 
 // IdP requests never carry the proxy's headers: LITELLM_HEADERS and provider headers can hold gateway credentials.
 async function discoverOidc(issuer: string, signal?: AbortSignal): Promise<OidcDiscovery> {
-  const withoutSlash = (value: string) => value.replace(/\/+$/, "");
-  const response = await fetch(`${withoutSlash(issuer)}${OIDC_DISCOVERY_PATH}`, {
+  const response = await fetch(`${trimTrailingSlashes(issuer)}${OIDC_DISCOVERY_PATH}`, {
     headers: authRequestHeaders(),
     redirect: "manual",
     signal: boundedLoginSignal(signal),
   });
   if (!response.ok) throw new Error(`OIDC discovery failed (HTTP ${response.status})`);
   const data = await readAuthJson(response, signal, "OIDC discovery");
-  if (!isPlainObject(data) || typeof data.issuer !== "string" || withoutSlash(data.issuer) !== withoutSlash(issuer))
+  if (
+    !isPlainObject(data) ||
+    typeof data.issuer !== "string" ||
+    trimTrailingSlashes(data.issuer) !== trimTrailingSlashes(issuer)
+  )
     throw new Error("OIDC discovery issuer does not match the configured issuer");
   const methods = data.code_challenge_methods_supported;
   if (methods !== undefined && (!Array.isArray(methods) || !methods.includes("S256")))
@@ -1100,9 +1509,9 @@ async function requestOidcToken(
       access: idToken,
       // The refresh token is optional, and an IdP that does not rotate it keeps the existing one valid.
       refresh: isAuthToken(refreshToken) ? refreshToken : existingRefreshToken,
-      // Refresh ahead of expiry, but by at most half the remaining lifetime, so a short-lived id_token is
-      // still used rather than treated as already expired.
-      expires: expiresAt - Math.ceil(Math.min(TOKEN_REFRESH_LEAD_MS, (expiresAt - Date.now()) / 2)),
+      // The exact expiry, as for PKCE: Pi already refreshes five minutes before it, and a transient refresh
+      // failure then keeps the id_token until it actually expires.
+      expires: expiresAt,
       subject: claims.sub,
     },
   };
@@ -1158,6 +1567,7 @@ async function loginOidc(interaction: AuthInteraction, baseUrl: string, config:
         clientId: config.clientId,
         tokenEndpoint: discovery.tokenEndpoint,
         subject: result.token.subject,
+        scope: config.scope,
       };
       return { ...credential, type: "oauth" };
     },
@@ -1312,11 +1722,69 @@ async function loginWithPastedToken(
   return { type: "oauth", access, refresh: "", expires, baseUrl };
 }
 
+const SIGN_IN_OIDC = "oidc";
+const SIGN_IN_PREVIOUS_OIDC = "previous-oidc";
+
+/**
+ * The stored login's identity provider, so signing in with it again takes one keypress. Enter picks it, so only a
+ * login to this proxy that recorded its scope qualifies: a guess could hand the IdP's token to another proxy or drop
+ * `offline_access`.
+ */
+function previousOidcConfig(definition: ProviderDefinition, baseUrl: string): OidcConfig | undefined {
+  const stored = readStoredCredential(definition.name, join(getAgentDir(), "auth.json"));
+  if (
+    stored?.type !== "oauth" ||
+    stored.flow !== OIDC_FLOW ||
+    stored.baseUrl !== baseUrl ||
+    typeof stored.scope !== "string"
+  )
+    return undefined;
+  try {
+    return parseOidcConfig({ issuer: stored.issuer, clientId: stored.clientId, scope: stored.scope });
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Without an `oidc` setting, asks whether to sign in through LiteLLM or directly with an identity provider
+ * where the user has a public client. Any answer but an identity provider selects the LiteLLM-hosted flows.
+ */
+async function promptOidcConfig(
+  interaction: AuthInteraction,
+  definition: ProviderDefinition,
+  baseUrl: string,
+): Promise<OidcConfig | undefined> {
+  const previous = previousOidcConfig(definition, baseUrl);
+  const choice = await interaction.prompt({
+    type: "select",
+    message: "Sign in with:",
+    options: [
+      ...(previous
+        ? [{ id: SIGN_IN_PREVIOUS_OIDC, label: `${previous.issuer} with client ${previous.clientId} (previous login)` }]
+        : []),
+      { id: "litellm", label: "LiteLLM SSO" },
+      { id: SIGN_IN_OIDC, label: "Your identity provider (OIDC client ID)…" },
+    ],
+  });
+  if (choice === SIGN_IN_PREVIOUS_OIDC) return previous;
+  if (choice !== SIGN_IN_OIDC) return undefined;
+  const ask = async (message: string, placeholder?: string) =>
+    (await interaction.prompt({ type: "text", message, placeholder })).trim();
+  // Checked like the setting. redirectPorts stays settings-only, for IdPs that pin exact loopback ports.
+  return parseOidcConfig({
+    issuer: await ask("Enter your identity provider's issuer URL:", "https://idp.example.com"),
+    clientId: await ask("Enter the OAuth client ID (a public client without a secret):"),
+    scope: (await ask("Enter scopes (blank for openid):", "openid offline_access")) || undefined,
+  });
+}
+
 async function loginOAuth(interaction: AuthInteraction, definition: ProviderDefinition): Promise<OAuthCredential> {
-  const oidc = definition.oidc === undefined ? undefined : parseOidcConfig(definition.oidc);
+  const configured = definition.oidc === undefined ? undefined : parseOidcConfig(definition.oidc);
   const baseUrl = await promptBaseUrl(interaction, definition);
   // Direct OIDC sends nothing to the proxy. The IdP is never derived from it either: the proxy's own OAuth
   // metadata describes LiteLLM's authorization server, not the IdP that signs the JWTs it accepts.
+  const oidc = configured ?? (await promptOidcConfig(interaction, definition, baseUrl));
   if (oidc) return loginOidc(interaction, baseUrl, oidc);
   const headers = resolveHeaders(definition);
   const discovery = await discoverPkce(baseUrl, interaction.signal, headers);
@@ -1444,11 +1912,9 @@ async function configuredBaseUrl(
   ctx: { env(name: string): Promise<string | undefined> },
   credential?: ApiKeyCredential,
 ): Promise<string | undefined> {
-  return (
-    cleanConfig(credential?.env?.[ENV_BASE_URL]) ??
-    cleanConfig(definition.baseUrl) ??
-    (definition.useDefaultEnv ? cleanConfig(await ctx.env(ENV_BASE_URL)) : undefined)
-  );
+  const scopedEnv = definition.envPrefix ? cleanConfig(await ctx.env(`${definition.envPrefix}_BASE_URL`)) : undefined;
+  const defaultEnv = definition.useDefaultEnv ? cleanConfig(await ctx.env(ENV_BASE_URL)) : undefined;
+  return cleanConfig(credential?.env?.[ENV_BASE_URL]) ?? cleanConfig(definition.baseUrl) ?? scopedEnv ?? defaultEnv;
 }
 
 async function resolveApiKeyAuth(
@@ -1470,39 +1936,73 @@ async function resolveApiKeyAuth(
       apiKey: stored,
     };
   } else {
-    creds = await resolveCredentials(
-      { ...definition, apiKeyConfig: undefined, useDefaultEnv: false },
-      { executeHelpers },
-    );
-    if (!creds.apiKey && definition.apiKeyConfig) {
+    // 1) Google ADC
+    const useGcloudToken = definition.useDefaultEnv
+      ? definition.useGcloudTokenAuth && isGcloudTokenAuthEnabled()
+      : definition.useGcloudTokenAuth;
+    const gcloudKey = executeHelpers && useGcloudToken ? (await getGcloudToken())?.trim() : undefined;
+    let apiKey = gcloudKey;
+    let apiKeyConfig: string | undefined;
+    if (gcloudKey) {
+      source = GCLOUD_ADC_SOURCE;
+    }
+
+    // 2) definition.apiKeyConfig
+    if (!apiKey && definition.apiKeyConfig) {
       const configured = definition.apiKeyConfig.startsWith("!")
         ? executeHelpers
           ? executeApiKeyCommand(definition.apiKeyConfig)
           : undefined
         : await resolveTemplateConfigValueFromContext(definition.apiKeyConfig, ctx.env);
       if (configured) {
-        creds.apiKey = configured;
-        creds.apiKeyConfig = definition.apiKeyConfig;
+        apiKey = configured;
+        apiKeyConfig = definition.apiKeyConfig;
+        source = definition.apiKeyConfig;
       } else if (!definition.apiKeyConfig.startsWith("!")) {
         warnUnresolvedApiKeyConfig(definition.name, definition.apiKeyConfig);
       }
     }
-    if (!creds.apiKey && definition.useDefaultEnv) {
+
+    // 3) Scoped envPrefix: _API_KEY_HELPER then _API_KEY
+    if (!apiKey && definition.envPrefix) {
+      const helper = normalizeCommand(await ctx.env(`${definition.envPrefix}_API_KEY_HELPER`));
+      if (helper) {
+        apiKey = executeHelpers ? executeApiKeyCommand(helper) : undefined;
+        apiKeyConfig = helper;
+        source = `$${definition.envPrefix}_API_KEY_HELPER`;
+      } else {
+        const envKey = cleanConfig(await ctx.env(`${definition.envPrefix}_API_KEY`));
+        if (envKey) {
+          apiKey = envKey;
+          apiKeyConfig = `$${definition.envPrefix}_API_KEY`;
+          source = `$${definition.envPrefix}_API_KEY`;
+        }
+      }
+    }
+
+    // 4) Default env: LITELLM_API_KEY_HELPER then LITELLM_API_KEY
+    if (!apiKey && definition.useDefaultEnv) {
       const helper = normalizeCommand(await ctx.env(ENV_API_KEY_HELPER));
       if (helper) {
-        creds.apiKey = executeHelpers ? executeApiKeyCommand(helper) : undefined;
-        creds.apiKeyConfig = helper;
+        apiKey = executeHelpers ? executeApiKeyCommand(helper) : undefined;
+        apiKeyConfig = helper;
         source = ENV_API_KEY_HELPER;
       } else {
         const envKey = cleanConfig(await ctx.env(ENV_API_KEY));
         if (envKey) {
-          creds.apiKey = envKey;
-          creds.apiKeyConfig = ENV_API_KEY;
+          apiKey = envKey;
+          apiKeyConfig = ENV_API_KEY;
           source = ENV_API_KEY;
         }
       }
     }
-    if (!creds.baseUrl && baseUrl) creds.baseUrl = normalizeBaseUrl(baseUrl, definition.allowInsecureHttp);
+
+    creds = {
+      baseUrl: baseUrl ? normalizeBaseUrl(baseUrl, definition.allowInsecureHttp) : undefined,
+      apiKey: apiKey || undefined,
+      apiKeyConfig,
+      apiKeyFromGcloudAdc: Boolean(gcloudKey),
+    };
   }
   if (!creds.apiKey) return undefined;
   const normalizedRoot = baseUrl ? normalizeBaseUrl(baseUrl, definition.allowInsecureHttp) : undefined;
@@ -1541,18 +2041,16 @@ function createProviderAuth(
   return {
     apiKey: {
       name: `${definition.displayName} API key`,
-      login:
-        definition.name === PROVIDER_NAME
-          ? async (interaction) => {
-              loginHooks?.start();
-              const credential = await loginApiKey(interaction, definition);
-              return completeLogin(credential);
-            }
-          : undefined,
+      login: async (interaction) => {
+        loginHooks?.start();
+        const credential = await loginApiKey(interaction, definition);
+        return completeLogin(credential);
+      },
       check: async ({ ctx, credential }) => {
         const baseUrl =
           credential?.env?.[ENV_BASE_URL] ??
           definition.baseUrl ??
+          (definition.envPrefix ? await ctx.env(`${definition.envPrefix}_BASE_URL`) : undefined) ??
           (definition.useDefaultEnv ? await ctx.env(ENV_BASE_URL) : undefined);
         if (!cleanConfig(baseUrl)) return undefined;
         if (credential?.key) return { type: "api_key", source: "stored credential" };
@@ -1565,6 +2063,14 @@ function createProviderAuth(
               : await resolveTemplateConfigValueFromContext(definition.apiKeyConfig, ctx.env);
             if (configuredKey) return definition.apiKeyConfig;
           }
+          if (definition.envPrefix) {
+            if (cleanConfig(await ctx.env(`${definition.envPrefix}_API_KEY_HELPER`))) {
+              return `$${definition.envPrefix}_API_KEY_HELPER`;
+            }
+            if (cleanConfig(await ctx.env(`${definition.envPrefix}_API_KEY`))) {
+              return `$${definition.envPrefix}_API_KEY`;
+            }
+          }
           if (definition.useDefaultEnv && cleanConfig(await ctx.env(ENV_API_KEY_HELPER))) return ENV_API_KEY_HELPER;
           if (definition.useDefaultEnv && cleanConfig(await ctx.env(ENV_API_KEY))) return ENV_API_KEY;
           return undefined;
@@ -1574,8 +2080,10 @@ function createProviderAuth(
         // key, the helper and the environment key. Whether the refresh token still mints
         // is only knowable at request time, and this must not make a network call; if it
         // fails, `resolve` falls back and reports the credential it actually used.
-        if (definition.useGcloudTokenAuth && isGcloudTokenAuthEnabled() && (await hasGcloudAdcCredentials()))
-          return { type: "api_key", source: GCLOUD_ADC_SOURCE };
+        const useGcloudToken = definition.useDefaultEnv
+          ? definition.useGcloudTokenAuth && isGcloudTokenAuthEnabled()
+          : definition.useGcloudTokenAuth;
+        if (useGcloudToken && (await hasGcloudAdcCredentials())) return { type: "api_key", source: GCLOUD_ADC_SOURCE };
         const fallback = await fallbackSource();
         return fallback ? { type: "api_key", source: fallback } : undefined;
       },
@@ -1883,7 +2391,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
         "Update Pi, or install the last release for older Pi: pi install npm:pi-provider-litellm@3.4.0",
     );
   }
-  const settings = await readGlobalLiteLLMSettings();
+  const settings = mergeProviderSettings(await readGlobalLiteLLMSettings(), await readModelsProviderSettings());
   const definitions = getProviderDefinitions(settings);
   const skillsEnabled = isFeatureEnabled(settings, "skills");
   const mcpEnabled = isFeatureEnabled(settings, "mcp");
@@ -1930,7 +2438,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   const mcpAttempts = new Map<string, { identity: string; registered: boolean }>();
   const mcpIdentitySalt = randomBytes(32);
 
-  function mcpServerConfig(definition: ProviderDefinition): McpServerConfig | undefined {
+  function mcpServerConfig(definition: ProviderDefinition): (McpServerConfig & { url: string }) | undefined {
+    if (definition.enableMcp === false) return undefined;
     if (discoveryDisabledReason() || isHostOffline()) return undefined;
     let root: string;
     try {
@@ -1947,7 +2456,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
       ...(headers ? { headers: Object.fromEntries(Object.entries(headers).map(([k, v]) => [k, piLiteral(v)])) } : {}),
       ...(mcpSettings?.exposure !== undefined ? { exposure: mcpSettings.exposure } : {}),
       ...(mcpSettings?.toolExposure !== undefined ? { toolExposure: mcpSettings.toolExposure } : {}),
-    } as McpServerConfig;
+    } as McpServerConfig & { url: string };
   }
 
   function dropMcpServer(definition: ProviderDefinition): void {
@@ -1956,7 +2465,66 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     if (attempt?.registered) pi.unregisterMcpServer(definition.name);
   }
 
-  function syncMcpServer(definition: ProviderDefinition): void {
+  // LiteLLM 1.102.0 and later answer `initialize` with 403 when the key has no MCP servers granted,
+  // and Pi warns at every start about a server that fails to connect. Asking first lets such a
+  // server be registered disabled: Pi neither connects to it nor warns, and /mcp still lists it, so
+  // the user can enable it once servers are granted.
+  async function mcpAccessRefused(definition: ProviderDefinition, url: string): Promise<boolean> {
+    try {
+      const stored = readStoredCredential(definition.name, join(getAgentDir(), "auth.json"));
+      // The check must send the credential Pi will send. Like seeding, it runs no key helper and
+      // mints no ADC token, and resolving without them would fall through to another key.
+      const useGcloudToken = definition.useDefaultEnv
+        ? definition.useGcloudTokenAuth && isGcloudTokenAuthEnabled()
+        : definition.useGcloudTokenAuth;
+      if (
+        (stored?.type === "api_key" && stored.key?.startsWith("!")) ||
+        definition.apiKeyConfig?.startsWith("!") ||
+        useGcloudToken
+      ) {
+        return false;
+      }
+      const auth = await authForCredential(definition, stored, false);
+      // The credential goes only to its own root.
+      if (`${auth.baseUrl}/mcp` !== url) return false;
+      // The credential and headers Pi's client sends, so the proxy answers as it will answer Pi.
+      const headers = { ...auth.headers, Authorization: `Bearer ${auth.apiKey}` };
+      const response = await fetch(url, {
+        method: "POST",
+        headers: { ...headers, accept: "application/json, text/event-stream", "content-type": "application/json" },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 1,
+          method: "initialize",
+          params: {
+            protocolVersion: "2025-06-18",
+            capabilities: {},
+            clientInfo: { name: "pi", version: piCodingAgent.VERSION },
+          },
+        }),
+        redirect: "manual",
+        signal: AbortSignal.timeout(getSeedTimeoutMs()),
+      });
+      await response.body?.cancel().catch(() => undefined);
+      // Pi opens its own session; end the one this check opened.
+      const session = response.headers.get("mcp-session-id");
+      if (session) {
+        void fetch(url, {
+          method: "DELETE",
+          headers: { ...headers, "mcp-session-id": session },
+          redirect: "manual",
+          signal: AbortSignal.timeout(getSeedTimeoutMs()),
+        })
+          .then((closed) => closed.body?.cancel())
+          .catch(() => undefined);
+      }
+      return response.status === 403;
+    } catch {
+      return false;
+    }
+  }
+
+  async function syncMcpServer(definition: ProviderDefinition): Promise<void> {
     const config = mcpServerConfig(definition);
     const identity = config && createHmac("sha256", mcpIdentitySalt).update(JSON.stringify(config)).digest("hex");
     if (identity === mcpAttempts.get(definition.name)?.identity) return;
@@ -1964,12 +2532,17 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     // Pi refuses the new config.
     dropMcpServer(definition);
     if (!config || !identity) return;
+    // Claimed before the access check, so the next turn does not repeat it, and a login that starts
+    // meanwhile drops the claim before this registration can land.
+    const attempt = { identity, registered: false };
+    mcpAttempts.set(definition.name, attempt);
+    const refused = await mcpAccessRefused(definition, config.url);
+    if (mcpAttempts.get(definition.name) !== attempt) return;
     try {
-      pi.registerMcpServer(definition.name, config);
-      mcpAttempts.set(definition.name, { identity, registered: true });
+      pi.registerMcpServer(definition.name, refused ? { ...config, enabled: false } : config);
+      attempt.registered = true;
     } catch (error) {
-      // Remembered so the refusal is reported once rather than on every turn.
-      mcpAttempts.set(definition.name, { identity, registered: false });
+      // The claim stays, so the refusal is reported once rather than on every turn.
       notifyMcp(
         `LiteLLM MCP (${JSON.stringify(definition.name)}): ${error instanceof Error ? error.message : String(error)}`,
       );
@@ -2074,7 +2647,13 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   // Pi's startup path only ever refreshes with allowNetwork:false, and it returns before the
   // network phase, so the provider would stay empty until the user opens /model. Discover here
   // instead, the way 1.x did, and hand the catalog over as the provider's baseline models.
-  async function seedModels(definition: ProviderDefinition): Promise<Model<LiteLLMApi>[]> {
+  //
+  // That is true on a first run. Once Pi has persisted the catalog it is not: with discovery off and a populated store,
+  // Pi offers the stored models and a request works. So the round trip -- about 1.8 s against a real proxy, on the
+  // critical path of every start -- is replaced by reading that catalog while it is fresh (models-store.ts). Nothing is
+  // written: Pi owns the file. The stored models are handed over rather than an empty list, so that a store Pi keeps
+  // somewhere else cannot leave the provider with nothing.
+  async function seedModels(definition: ProviderDefinition): Promise<(Model<LiteLLMApi> | LiteLLMImageModel)[]> {
     const disabledReason = discoveryDisabledReason() ?? (isHostOffline() ? "PI_OFFLINE" : null);
     if (disabledReason) {
       if (isVerboseDiscovery()) {
@@ -2082,13 +2661,31 @@ export default async function (pi: ExtensionAPI): Promise<void> {
       }
       return [];
     }
+    const agentDir = getAgentDir();
     try {
-      const stored = readStoredCredential(definition.name, join(getAgentDir(), "auth.json"));
+      const stored = readStoredCredential(definition.name, join(agentDir, "auth.json"));
       // executeHelpers:false — activation must never run the user's key helper as a side effect,
       // so helper-backed setups keep waiting for Pi's own refresh.
       const auth = await authForCredential(definition, stored, false);
+      const storedModels = await readStoredModels({
+        agentDir,
+        provider: definition.name,
+        baseUrl: normalizeBaseUrl(auth.baseUrl, auth.allowInsecureHttp),
+        allowInsecureHttp: definition.allowInsecureHttp,
+      });
+      if (storedModels) {
+        if (isVerboseDiscovery()) {
+          process.stderr.write(
+            `LiteLLM (${definition.name}): startup discovery skipped (${storedModels.length} model(s) from Pi's store).\n`,
+          );
+        }
+        return storedModels;
+      }
       const result = await runDiscovery(auth, AbortSignal.timeout(getSeedTimeoutMs()));
-      return toNativeModels(definition.name, result.baseUrl, result.models, definition.allowInsecureHttp);
+      return [
+        ...toNativeModels(definition.name, result.baseUrl, result.models, definition.allowInsecureHttp),
+        ...toNativeImageModels(definition.name, result.baseUrl, result.imageModels ?? [], definition.allowInsecureHttp),
+      ];
     } catch (error) {
       // No credentials yet is the normal unconfigured case; anything else is worth one line.
       if (isVerboseDiscovery()) {
@@ -2100,26 +2697,30 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     }
   }
 
-  const seeded = await Promise.all(definitions.map(seedModels));
+  // The MCP access check overlaps seeding rather than adding to startup. Servers registered while
+  // the extension loads connect when the session starts.
+  const [seeded] = await Promise.all([
+    Promise.all(definitions.map(seedModels)),
+    mcpEnabled ? Promise.all(definitions.map(syncMcpServer)) : undefined,
+  ]);
   // Pi runs a provider's network phase only once a credential resolves, so /litellm-refresh reads an
   // unchanged count as "no credentials" rather than as a successful refresh.
   const networkRefreshAttempts = new Map<string, number>();
 
   for (const [index, definition] of definitions.entries()) {
+    const loginHooks = {
+      // Disconnect before the login can store a new credential: Pi's MCP client reads the
+      // provider's current token on every request, including the session teardown, so a
+      // connection still open to the old proxy root would send it the new credential.
+      start: () => dropMcpServer(definition),
+      complete: () => {
+        loginGeneration++;
+      },
+    };
     const auth = createProviderAuth(
       definition,
       () => oauthRuntimeRoots.delete(definition.name),
-      definition.name === PROVIDER_NAME
-        ? {
-            // Disconnect before the login can store a new credential: Pi's MCP client reads the
-            // provider's current token on every request, including the session teardown, so a
-            // connection still open to the old proxy root would send it the new credential.
-            start: () => dropMcpServer(definition),
-            complete: () => {
-              loginGeneration++;
-            },
-          }
-        : undefined,
+      loginHooks,
       () => oauthRuntimeRoots.get(definition.name),
     );
     if (auth.oauth) {
@@ -2315,11 +2916,9 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   });
 
   if (mcpEnabled) {
-    // Servers registered while the extension loads connect when the session starts. Each turn
-    // picks up a login that changed the proxy root, and a logout that removed it.
-    for (const definition of definitions) syncMcpServer(definition);
-    pi.on("before_agent_start", () => {
-      for (const definition of definitions) syncMcpServer(definition);
+    // Each turn picks up a login that changed the proxy root, and a logout that removed it.
+    pi.on("before_agent_start", async () => {
+      await Promise.all(definitions.map(syncMcpServer));
     });
   }