pi-cache-optimizer 2.4.6 → 2.4.8

package/index.ts

@@ -91,6 +91,15 @@ const MIN_STABLE_CANDIDATE_LENGTH = 8;
 const ASSISTANT_MESSAGE_MODEL_TOKEN_KEYS = ["model", "name"];
 const OPENAI_REASONING_MODEL_PATTERN = /(^|[/\s:_-])o[1345]($|[-_.:/\s])/;
 const XAI_MODEL_PATTERN = /(^|[/\s:_-])xai($|[-_.:/\s])/;
+const PPLX_MODEL_PATTERN = /(^|[/\s:_-])pplx($|[-_.:/\s])/i;
+const NOVA_MODEL_PATTERN = /(^|[/\s:_-])nova($|[-_.:/\s])/i;
+const MPT_MODEL_PATTERN = /(^|[/\s:_-])mpt($|[-_.:/\s])/i;
+const ALEPH_MODEL_PATTERN = /(^|[/\s:_-])aleph($|[-_.:/\s])/i;
+
+// Safe-boundary patterns for models with short or ambiguous tokens
+const ARCTIC_MODEL_PATTERN = /(^|[\/\s:_-])arctic($|[\-_.:\/\s])/i;
+const AYA_MODEL_PATTERN = /(^|[\/\s:_-])aya($|[\-_.:\/\s])/i;
+const ORION_MODEL_PATTERN = /(^|[\/\s:_-])orion($|[\-_.:\/\s])/i;
 
 type CacheCompat = {
   sendSessionAffinityHeaders?: boolean;
@@ -847,6 +856,285 @@ function isSolarLikeAssistantMessage(message: unknown, model: PiModel | undefine
   return modelOrAssistantMessageHas(message, model, ["solar", "upstage"]);
 }
 
+// ── New OpenAI-compatible model detection (batch 3, 12 families) ──────
+
+// Perplexity / Sonar
+function isPerplexityLikeModel(model: PiModel | undefined): boolean {
+  const tokens = getModelIdNameTokenValues(model);
+  return hasAnyTokenContaining(tokens, ["sonar", "perplexity"]) || tokens.some((t) => PPLX_MODEL_PATTERN.test(t));
+}
+function isPerplexityLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  const allTokens = [
+    ...getModelIdNameTokenValues(model),
+    ...getAssistantMessageModelTokenValues(message),
+  ];
+  return hasAnyTokenContaining(allTokens, ["sonar", "perplexity"]) || allTokens.some((t) => PPLX_MODEL_PATTERN.test(t));
+}
+
+// Amazon Nova
+function isNovaLikeModel(model: PiModel | undefined): boolean {
+  const tokens = getModelIdNameTokenValues(model);
+  return hasAnyTokenContaining(tokens, ["amazon-nova"]) || tokens.some((t) => NOVA_MODEL_PATTERN.test(t));
+}
+function isNovaLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  const allTokens = [
+    ...getModelIdNameTokenValues(model),
+    ...getAssistantMessageModelTokenValues(message),
+  ];
+  return hasAnyTokenContaining(allTokens, ["amazon-nova"]) || allTokens.some((t) => NOVA_MODEL_PATTERN.test(t));
+}
+
+// Reka
+function isRekaLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["reka"]);
+}
+function isRekaLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["reka"]);
+}
+
+// Falcon / TII
+function isFalconLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["falcon", "tiiuae"]);
+}
+function isFalconLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["falcon", "tiiuae"]);
+}
+
+// Databricks DBRX
+function isDbrxLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["dbrx", "databricks"]);
+}
+function isDbrxLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["dbrx", "databricks"]);
+}
+
+// MosaicML MPT
+function isMptLikeModel(model: PiModel | undefined): boolean {
+  const tokens = getModelIdNameTokenValues(model);
+  return hasAnyTokenContaining(tokens, ["mosaicml", "mpt-"]) || tokens.some((t) => MPT_MODEL_PATTERN.test(t));
+}
+function isMptLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  const allTokens = [
+    ...getModelIdNameTokenValues(model),
+    ...getAssistantMessageModelTokenValues(message),
+  ];
+  return hasAnyTokenContaining(allTokens, ["mosaicml", "mpt-"]) || allTokens.some((t) => MPT_MODEL_PATTERN.test(t));
+}
+
+// StableLM / Stability AI
+function isStableLMLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["stablelm", "stable-lm", "stability-ai"]);
+}
+function isStableLMLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["stablelm", "stable-lm", "stability-ai"]);
+}
+
+// BAAI / Aquila
+function isAquilaLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["aquila", "baai"]);
+}
+function isAquilaLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["aquila", "baai"]);
+}
+
+// LG EXAONE
+function isExaoneLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["exaone"]);
+}
+function isExaoneLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["exaone"]);
+}
+
+// Naver HyperCLOVA X (conservative: hyperclova, clova-x only)
+function isHyperCLOVALikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["hyperclova", "clova-x"]);
+}
+function isHyperCLOVALikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["hyperclova", "clova-x"]);
+}
+
+// Aleph Alpha Luminous
+function isLuminousLikeModel(model: PiModel | undefined): boolean {
+  const tokens = getModelIdNameTokenValues(model);
+  return hasAnyTokenContaining(tokens, ["luminous", "aleph-alpha"]) || tokens.some((t) => ALEPH_MODEL_PATTERN.test(t));
+}
+function isLuminousLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  const allTokens = [
+    ...getModelIdNameTokenValues(model),
+    ...getAssistantMessageModelTokenValues(message),
+  ];
+  return hasAnyTokenContaining(allTokens, ["luminous", "aleph-alpha"]) || allTokens.some((t) => ALEPH_MODEL_PATTERN.test(t));
+}
+
+// Nous / Hermes / OpenHermes
+function isHermesLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["nous", "hermes", "openhermes"]);
+}
+function isHermesLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["nous", "hermes", "openhermes"]);
+}
+
+// ── More OpenAI-compatible model detection (batch 4, 18 families) ──
+
+// IBM Granite
+function isGraniteLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["granite", "ibm-granite"]);
+}
+function isGraniteLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["granite", "ibm-granite"]);
+}
+
+// Snowflake Arctic
+function isArcticLikeModel(model: PiModel | undefined): boolean {
+  const tokens = getModelIdNameTokenValues(model);
+  return hasAnyTokenContaining(tokens, ["snowflake-arctic"]) || tokens.some((t) => ARCTIC_MODEL_PATTERN.test(t));
+}
+function isArcticLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  const allTokens = [
+    ...getModelIdNameTokenValues(model),
+    ...getAssistantMessageModelTokenValues(message),
+  ];
+  return hasAnyTokenContaining(allTokens, ["snowflake-arctic"]) || allTokens.some((t) => ARCTIC_MODEL_PATTERN.test(t));
+}
+
+// Huawei Pangu / 盘古
+function isPanguLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["pangu", "pan-gu", "盘古", "huawei-pangu"]);
+}
+function isPanguLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["pangu", "pan-gu", "盘古", "huawei-pangu"]);
+}
+
+// SenseTime SenseNova / 商汤
+function isSenseNovaLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["sensenova", "sense-nova", "sensechat", "商汤"]);
+}
+function isSenseNovaLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["sensenova", "sense-nova", "sensechat", "商汤"]);
+}
+
+// 360 Zhinao / 智脑
+function isZhinaoLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["360gpt", "360-gpt", "zhinao", "智脑"]);
+}
+function isZhinaoLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["360gpt", "360-gpt", "zhinao", "智脑"]);
+}
+
+// OpenBMB MiniCPM
+function isMiniCPMLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["minicpm", "mini-cpm", "openbmb"]);
+}
+function isMiniCPMLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["minicpm", "mini-cpm", "openbmb"]);
+}
+
+// XVERSE
+function isXVerseLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["xverse"]);
+}
+function isXVerseLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["xverse"]);
+}
+
+// OrionStar Orion
+function isOrionLikeModel(model: PiModel | undefined): boolean {
+  const tokens = getModelIdNameTokenValues(model);
+  return hasAnyTokenContaining(tokens, ["orionstar", "orion-star"]) || tokens.some((t) => ORION_MODEL_PATTERN.test(t));
+}
+function isOrionLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  const allTokens = [
+    ...getModelIdNameTokenValues(model),
+    ...getAssistantMessageModelTokenValues(message),
+  ];
+  return hasAnyTokenContaining(allTokens, ["orionstar", "orion-star"]) || allTokens.some((t) => ORION_MODEL_PATTERN.test(t));
+}
+
+// OpenChat
+function isOpenChatLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["openchat"]);
+}
+function isOpenChatLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["openchat"]);
+}
+
+// Vicuna
+function isVicunaLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["vicuna"]);
+}
+function isVicunaLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["vicuna"]);
+}
+
+// WizardLM / WizardCoder
+function isWizardLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["wizardlm", "wizard-lm", "wizardcoder", "wizard-coder"]);
+}
+function isWizardLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["wizardlm", "wizard-lm", "wizardcoder", "wizard-coder"]);
+}
+
+// Zephyr
+function isZephyrLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["zephyr"]);
+}
+function isZephyrLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["zephyr"]);
+}
+
+// Dolphin
+function isDolphinLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["dolphin"]);
+}
+function isDolphinLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["dolphin"]);
+}
+
+// OpenOrca
+function isOpenOrcaLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["openorca", "open-orca"]);
+}
+function isOpenOrcaLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["openorca", "open-orca"]);
+}
+
+// Starling
+function isStarlingLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["starling"]);
+}
+function isStarlingLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["starling"]);
+}
+
+// BLOOM / BigScience
+function isBloomLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["bloom", "bigscience"]);
+}
+function isBloomLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["bloom", "bigscience"]);
+}
+
+// RWKV
+function isRwkvLikeModel(model: PiModel | undefined): boolean {
+  return hasAnyTokenContaining(getModelIdNameTokenValues(model), ["rwkv"]);
+}
+function isRwkvLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  return modelOrAssistantMessageHas(message, model, ["rwkv"]);
+}
+
+// Cohere Aya
+function isAyaLikeModel(model: PiModel | undefined): boolean {
+  const tokens = getModelIdNameTokenValues(model);
+  return hasAnyTokenContaining(tokens, ["aya-expanse"]) || tokens.some((t) => AYA_MODEL_PATTERN.test(t));
+}
+function isAyaLikeAssistantMessage(message: unknown, model: PiModel | undefined): boolean {
+  const allTokens = [
+    ...getModelIdNameTokenValues(model),
+    ...getAssistantMessageModelTokenValues(message),
+  ];
+  return hasAnyTokenContaining(allTokens, ["aya-expanse"]) || allTokens.some((t) => AYA_MODEL_PATTERN.test(t));
+}
+
 // ── Model key ──────────────────────────────────────────────────────
 
 function modelKey(model: PiModel): string {
@@ -1594,134 +1882,646 @@ const CACHE_PROVIDER_ADAPTERS: CacheProviderAdapter[] = [
       return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
     },
   },
-];
-
-function selectAdapterForModel(model: PiModel | undefined): CacheProviderAdapter | undefined {
-  return CACHE_PROVIDER_ADAPTERS.find((adapter) => adapter.matchesModel(model));
-}
-
-function selectAdapterForAssistantMessage(message: unknown, model: PiModel | undefined): CacheProviderAdapter | undefined {
-  return CACHE_PROVIDER_ADAPTERS.find((adapter) => adapter.matchesAssistantMessage(message, model));
-}
-
-function notifyCacheCompatIfNeeded(
-  model: PiModel | undefined,
-  ctx: ExtensionContext,
-  warnedModels: Set<string>,
-): void {
-  if (!model) return;
-
-  const adapter = selectAdapterForModel(model);
-  const text = adapter?.warningText?.(model);
-  if (!adapter || !text) return;
-
-  const key = `${adapter.id}:${modelKey(model)}`;
-  if (warnedModels.has(key)) return;
-  warnedModels.add(key);
-
-  ctx.ui.notify(text, "warning");
-}
-
-function currentLocalDay(): string {
-  const now = new Date();
-  const year = now.getFullYear();
-  const month = String(now.getMonth() + 1).padStart(2, "0");
-  const day = String(now.getDate()).padStart(2, "0");
-  return `${year}-${month}-${day}`;
-}
-
-function emptyCacheStats(day = currentLocalDay()): CacheStats {
-  return {
-    day,
-    totalRequests: 0,
-    hitRequests: 0,
-    cachedInputTokens: 0,
-    cacheWriteInputTokens: 0,
-    totalInputTokens: 0,
-  };
-}
-
-function emptyAllCacheStats(day = currentLocalDay()): Partial<Record<CacheProviderId, CacheStats>> {
-  return Object.fromEntries(CACHE_PROVIDER_IDS.map((id) => [id, emptyCacheStats(day)])) as Partial<Record<CacheProviderId, CacheStats>>;
-}
-
-function addUsageToCacheStats(stats: CacheStats, usage: UsageSnapshot): void {
-  stats.totalRequests += 1;
-  if (usage.cacheRead > 0) stats.hitRequests += 1;
-  stats.cachedInputTokens += usage.cacheRead;
-  stats.cacheWriteInputTokens += usage.cacheWrite;
-  stats.totalInputTokens += usage.totalInput;
-}
-
-function formatTokenCount(value: number): string {
-  const millions = Math.max(0, Math.round(value)) / 1_000_000;
-  if (millions === 0) return "0M";
-  if (millions < 0.001) return `${millions.toFixed(4)}M`;
-  if (millions < 0.01) return `${millions.toFixed(3)}M`;
-  if (millions >= 10) return `${millions.toFixed(1)}M`;
-  return `${millions.toFixed(2)}M`;
-}
-
-function formatCacheStats(adapter: CacheProviderAdapter, stats: CacheStats): string {
-  const percent = stats.totalInputTokens > 0
-    ? ` (${Math.round((stats.cachedInputTokens / stats.totalInputTokens) * 100)}%)`
-    : "";
-  const writeText = adapter.showCacheWrite && stats.cacheWriteInputTokens > 0
-    ? ` · write ${formatTokenCount(stats.cacheWriteInputTokens)} tok`
-    : "";
-
-  return `${adapter.label} ${stats.hitRequests}/${stats.totalRequests} · ${formatTokenCount(stats.cachedInputTokens)}/${formatTokenCount(stats.totalInputTokens)} tok${percent}${writeText}`;
-}
-
-function getErrorCode(error: unknown): string | undefined {
-  return typeof error === "object" && error !== null && "code" in error
-    ? String((error as { code?: unknown }).code)
-    : undefined;
-}
-
-function parseCacheStats(value: unknown): CacheStats | undefined {
-  const stats = asRecord(value);
-  if (!stats || typeof stats.day !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(stats.day)) {
-    return undefined;
-  }
-
-  const totalRequests = getNonNegativeNumber(stats, "totalRequests");
-  const hitRequests = getNonNegativeNumber(stats, "hitRequests");
-  const cachedInputTokens = getNonNegativeNumber(stats, "cachedInputTokens");
-  const cacheWriteInputTokens = getNonNegativeNumber(stats, "cacheWriteInputTokens") ?? 0;
-  const totalInputTokens = getNonNegativeNumber(stats, "totalInputTokens");
-
-  if (
-    totalRequests === undefined ||
-    hitRequests === undefined ||
-    cachedInputTokens === undefined ||
-    totalInputTokens === undefined ||
-    hitRequests > totalRequests ||
-    cachedInputTokens > totalInputTokens ||
-    cacheWriteInputTokens > totalInputTokens
-  ) {
-    return undefined;
-  }
-
-  return {
-    day: stats.day,
-    totalRequests,
-    hitRequests,
-    cachedInputTokens,
-    cacheWriteInputTokens,
-    totalInputTokens,
-  };
-}
-
-function parsePersistedCacheStats(value: unknown): CacheStatsState | undefined {
-  const record = asRecord(value);
-  if (!record) return undefined;
-
-  // version 3: model-scoped stats + legacy family fallback
-  if (record.version === 3) {
-    const statsByModel: Record<string, CacheStats> = {};
-    const rawModelMap = asRecord(record.statsByModel);
-    if (rawModelMap) {
+  // ── New OpenAI-compatible adapters (batch 3, 12 families) ────────
+  {
+    id: "openai" as CacheProviderId,
+    label: "Sonar cache",
+    matchesModel: isPerplexityLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isPerplexityLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Nova cache",
+    matchesModel: isNovaLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isNovaLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Reka cache",
+    matchesModel: isRekaLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isRekaLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Falcon cache",
+    matchesModel: isFalconLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isFalconLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "DBRX cache",
+    matchesModel: isDbrxLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isDbrxLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "MPT cache",
+    matchesModel: isMptLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isMptLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "StableLM cache",
+    matchesModel: isStableLMLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isStableLMLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Aquila cache",
+    matchesModel: isAquilaLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isAquilaLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "EXAONE cache",
+    matchesModel: isExaoneLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isExaoneLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "HyperCLOVA cache",
+    matchesModel: isHyperCLOVALikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isHyperCLOVALikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Luminous cache",
+    matchesModel: isLuminousLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isLuminousLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Hermes cache",
+    matchesModel: isHermesLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isHermesLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  // ── More OpenAI-compatible adapters (batch 4, 18 families) ────────
+  {
+    id: "openai" as CacheProviderId,
+    label: "Granite cache",
+    matchesModel: isGraniteLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isGraniteLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Arctic cache",
+    matchesModel: isArcticLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isArcticLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Pangu cache",
+    matchesModel: isPanguLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isPanguLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "SenseNova cache",
+    matchesModel: isSenseNovaLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isSenseNovaLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Zhinao cache",
+    matchesModel: isZhinaoLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isZhinaoLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "MiniCPM cache",
+    matchesModel: isMiniCPMLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isMiniCPMLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "XVERSE cache",
+    matchesModel: isXVerseLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isXVerseLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Orion cache",
+    matchesModel: isOrionLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isOrionLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "OpenChat cache",
+    matchesModel: isOpenChatLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isOpenChatLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Vicuna cache",
+    matchesModel: isVicunaLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isVicunaLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Wizard cache",
+    matchesModel: isWizardLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isWizardLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Zephyr cache",
+    matchesModel: isZephyrLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isZephyrLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Dolphin cache",
+    matchesModel: isDolphinLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isDolphinLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "OpenOrca cache",
+    matchesModel: isOpenOrcaLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isOpenOrcaLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Starling cache",
+    matchesModel: isStarlingLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isStarlingLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "BLOOM cache",
+    matchesModel: isBloomLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isBloomLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "RWKV cache",
+    matchesModel: isRwkvLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isRwkvLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "openai" as CacheProviderId,
+    label: "Aya cache",
+    matchesModel: isAyaLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isAyaLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+];
+
+function selectAdapterForModel(model: PiModel | undefined): CacheProviderAdapter | undefined {
+  return CACHE_PROVIDER_ADAPTERS.find((adapter) => adapter.matchesModel(model));
+}
+
+function selectAdapterForAssistantMessage(message: unknown, model: PiModel | undefined): CacheProviderAdapter | undefined {
+  return CACHE_PROVIDER_ADAPTERS.find((adapter) => adapter.matchesAssistantMessage(message, model));
+}
+
+function notifyCacheCompatIfNeeded(
+  model: PiModel | undefined,
+  ctx: ExtensionContext,
+  warnedModels: Set<string>,
+): void {
+  if (!model) return;
+
+  const adapter = selectAdapterForModel(model);
+  const text = adapter?.warningText?.(model);
+  if (!adapter || !text) return;
+
+  const key = `${adapter.id}:${modelKey(model)}`;
+  if (warnedModels.has(key)) return;
+  warnedModels.add(key);
+
+  ctx.ui.notify(text, "warning");
+}
+
+function currentLocalDay(): string {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function emptyCacheStats(day = currentLocalDay()): CacheStats {
+  return {
+    day,
+    totalRequests: 0,
+    hitRequests: 0,
+    cachedInputTokens: 0,
+    cacheWriteInputTokens: 0,
+    totalInputTokens: 0,
+  };
+}
+
+function emptyAllCacheStats(day = currentLocalDay()): Partial<Record<CacheProviderId, CacheStats>> {
+  return Object.fromEntries(CACHE_PROVIDER_IDS.map((id) => [id, emptyCacheStats(day)])) as Partial<Record<CacheProviderId, CacheStats>>;
+}
+
+function addUsageToCacheStats(stats: CacheStats, usage: UsageSnapshot): void {
+  stats.totalRequests += 1;
+  if (usage.cacheRead > 0) stats.hitRequests += 1;
+  stats.cachedInputTokens += usage.cacheRead;
+  stats.cacheWriteInputTokens += usage.cacheWrite;
+  stats.totalInputTokens += usage.totalInput;
+}
+
+function formatTokenCount(value: number): string {
+  const millions = Math.max(0, Math.round(value)) / 1_000_000;
+  if (millions === 0) return "0M";
+  if (millions < 0.001) return `${millions.toFixed(4)}M`;
+  if (millions < 0.01) return `${millions.toFixed(3)}M`;
+  if (millions >= 10) return `${millions.toFixed(1)}M`;
+  return `${millions.toFixed(2)}M`;
+}
+
+function formatCacheStats(adapter: CacheProviderAdapter, stats: CacheStats): string {
+  const percent = stats.totalInputTokens > 0
+    ? ` (${Math.round((stats.cachedInputTokens / stats.totalInputTokens) * 100)}%)`
+    : "";
+  const writeText = adapter.showCacheWrite && stats.cacheWriteInputTokens > 0
+    ? ` · write ${formatTokenCount(stats.cacheWriteInputTokens)} tok`
+    : "";
+
+  return `${adapter.label} ${stats.hitRequests}/${stats.totalRequests} · ${formatTokenCount(stats.cachedInputTokens)}/${formatTokenCount(stats.totalInputTokens)} tok${percent}${writeText}`;
+}
+
+function getErrorCode(error: unknown): string | undefined {
+  return typeof error === "object" && error !== null && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+}
+
+function parseCacheStats(value: unknown): CacheStats | undefined {
+  const stats = asRecord(value);
+  if (!stats || typeof stats.day !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(stats.day)) {
+    return undefined;
+  }
+
+  const totalRequests = getNonNegativeNumber(stats, "totalRequests");
+  const hitRequests = getNonNegativeNumber(stats, "hitRequests");
+  const cachedInputTokens = getNonNegativeNumber(stats, "cachedInputTokens");
+  const cacheWriteInputTokens = getNonNegativeNumber(stats, "cacheWriteInputTokens") ?? 0;
+  const totalInputTokens = getNonNegativeNumber(stats, "totalInputTokens");
+
+  if (
+    totalRequests === undefined ||
+    hitRequests === undefined ||
+    cachedInputTokens === undefined ||
+    totalInputTokens === undefined ||
+    hitRequests > totalRequests ||
+    cachedInputTokens > totalInputTokens ||
+    cacheWriteInputTokens > totalInputTokens
+  ) {
+    return undefined;
+  }
+
+  return {
+    day: stats.day,
+    totalRequests,
+    hitRequests,
+    cachedInputTokens,
+    cacheWriteInputTokens,
+    totalInputTokens,
+  };
+}
+
+function parsePersistedCacheStats(value: unknown): CacheStatsState | undefined {
+  const record = asRecord(value);
+  if (!record) return undefined;
+
+  // version 3: model-scoped stats + legacy family fallback
+  if (record.version === 3) {
+    const statsByModel: Record<string, CacheStats> = {};
+    const rawModelMap = asRecord(record.statsByModel);
+    if (rawModelMap) {
       for (const [key, val] of Object.entries(rawModelMap)) {
         const parsed = parseCacheStats(val);
         if (parsed) statsByModel[key] = parsed;
@@ -1821,6 +2621,171 @@ function isCompatCheckApplicable(model: PiModel): boolean {
   return lower(model.api) === "openai-completions" && !isOfficialOpenAIBaseUrl(model);
 }
 
+/**
+ * Detect router / channel profiles from a PiModel and return diagnostic notes.
+ *
+ * This function is advisory only — it does NOT participate in adapter selection,
+ * prompt_cache_key injection, or footer stats. It inspects provider, api, baseUrl,
+ * and compat to identify common proxy/router patterns where cache performance may
+ * be degraded due to multi-backend routing.
+ *
+ * Known profiles (checked in order):
+ *   1. OpenRouter — baseUrl or provider id matching openrouter.ai / openrouter
+ *   2. Vercel AI Gateway — baseUrl matching ai-gateway.vercel.sh, or provider
+ *      matching vercel / vercel-ai-gateway
+ *   3. LiteLLM / OneAPI / NewAPI / VoAPI — baseUrl or provider matching litellm,
+ *      oneapi, one-api, newapi, new-api, voapi, vo-api (self-hosted aggregation)
+ *   4. Generic third-party OpenAI-compatible proxy — any openai-completions model
+ *      with a non-official base URL that does not match a higher-profile above.
+ *
+ * Official OpenAI (api.openai.com) and custom transports (kiro-api, anthropic-messages,
+ * bedrock-converse-stream) do NOT produce notes.
+ */
+function describeRouterChannelDiagnostics(model: PiModel): string[] {
+  const notes: string[] = [];
+  const api = lower(model.api);
+  const baseUrl = lower(model.baseUrl || "");
+  const provider = lower(model.provider);
+
+  // Only OpenAI-compatible APIs are applicable for router/channel diagnostics.
+  // Custom transports like kiro-api, anthropic-messages, bedrock-converse-stream
+  // or non-OpenAI APIs are excluded.
+  if (api !== "openai-completions" && api !== "openai-responses") {
+    return notes;
+  }
+
+  // Official OpenAI bypass — no notes needed.
+  if (isOfficialOpenAIBaseUrl(model)) {
+    return notes;
+  }
+
+  // ── 1. OpenRouter ────────────────────────────────────────────────
+  if (
+    baseUrl.includes("openrouter.ai") ||
+    baseUrl.includes("openrouter") ||
+    provider.includes("openrouter")
+  ) {
+    const compat = getCompat(model);
+    const hasOnly = !!(compat as Record<string, unknown>)["openRouterRouting"]?.only;
+    const hasOrder = !!(compat as Record<string, unknown>)["openRouterRouting"]?.order;
+
+    notes.push(
+      "🔀 Router/channel: OpenRouter detected. OpenRouter is a multi-provider router; " +
+      "low cache hit rates are common when each turn lands on a different upstream provider.",
+    );
+
+    if (!hasOnly && !hasOrder) {
+      notes.push(
+        "   Suggestion: Add an openRouterRouting config to fix the upstream provider. " +
+        "Example for models.json -> providers[\"<providerId>\"] -> compat:",
+      );
+      notes.push(
+        `   { "sendSessionAffinityHeaders": true, "supportsLongCacheRetention": true, ` +
+        `"openRouterRouting": { "only": ["<provider-slug>"] } }`,
+      );
+      notes.push(
+        '   Replace <provider-slug> with the actual OpenRouter provider slug (e.g. "openai", "anthropic").',
+      );
+      notes.push(
+        "   Alternatively, use openRouterRouting.order: [\"<provider-slug>\", \"...\"] for fallback order. " +
+        "Only set supportsLongCacheRetention if your upstream supports long cache retention.",
+      );
+    }
+
+    return notes;
+  }
+
+  // ── 2. Vercel AI Gateway ─────────────────────────────────────────
+  if (
+    baseUrl.includes("ai-gateway.vercel.sh") ||
+    provider.includes("vercel") ||
+    provider.includes("vercel-ai-gateway")
+  ) {
+    const compat = getCompat(model);
+    const hasOnly = !!(compat as Record<string, unknown>)["vercelGatewayRouting"]?.only;
+    const hasOrder = !!(compat as Record<string, unknown>)["vercelGatewayRouting"]?.order;
+
+    notes.push(
+      "🔀 Router/channel: Vercel AI Gateway detected. The gateway may route to different " +
+      "provider endpoints per request, reducing cache locality.",
+    );
+
+    if (!hasOnly && !hasOrder) {
+      notes.push(
+        "   Suggestion: Add a vercelGatewayRouting config to fix the upstream. " +
+        "Example for models.json -> providers[\"<providerId>\"] -> compat:",
+      );
+      notes.push(
+        `   { "sendSessionAffinityHeaders": true, "supportsLongCacheRetention": true, ` +
+        `"vercelGatewayRouting": { "only": ["<provider-id>"] } }`,
+      );
+      notes.push(
+        "   Replace <provider-id> with the actual Vercel provider ID (e.g. \"openai\").",
+      );
+      notes.push(
+        "   Only set supportsLongCacheRetention if your upstream supports it.",
+      );
+    }
+
+    return notes;
+  }
+
+  // ── 3. LiteLLM / OneAPI / NewAPI / VoAPI (self-hosted aggregation) ──
+  const aggregationPatterns = ["litellm", "oneapi", "one-api", "newapi", "new-api", "voapi", "vo-api"];
+  if (
+    aggregationPatterns.some((p) => baseUrl.includes(p)) ||
+    aggregationPatterns.some((p) => provider.includes(p))
+  ) {
+    notes.push(
+      "🔀 Router/channel: Self-hosted aggregation proxy detected (LiteLLM / OneAPI / NewAPI / VoAPI). " +
+      "These proxies route to multiple upstream accounts or instances, which can split the cache.",
+    );
+    notes.push(
+      "   Suggestions:",
+    );
+    notes.push(
+      "   • Ensure the proxy can fix to a single upstream per session (session_id affinity).",
+    );
+    notes.push(
+      "   • Forward prompt_cache_key and session-affinity headers to the upstream.",
+    );
+    notes.push(
+      "   • Return cache usage fields (prompt_cache_hit_tokens, etc.) in the response.",
+    );
+    notes.push(
+      `   Example compat: { "sendSessionAffinityHeaders": true, "supportsLongCacheRetention": true }`,
+    );
+
+    return notes;
+  }
+
+  // ── 4. Generic third-party OpenAI-compatible proxy ─────────────────
+  if (api === "openai-completions" && baseUrl) {
+    const missing = describeMissingOpenAICompatibleProxyCompat(model);
+    notes.push(
+      "🔀 Router/channel: Third-party OpenAI-compatible proxy. If cache hit rates are low:",
+    );
+    notes.push(
+      "   • Verify the proxy routes to the same upstream account/instance per session.",
+    );
+    notes.push(
+      "   • Ensure the proxy forwards prompt_cache_key and sends session-affinity headers.",
+    );
+    notes.push(
+      "   • Check that the proxy returns cache usage fields (prompt_cache_hit_tokens etc.).",
+    );
+    if (missing.length > 0) {
+      notes.push(
+        `   • The compat flags above (${missing.join(", ")}) are recommended for cache stability.`,
+      );
+    }
+
+    return notes;
+  }
+
+  return notes;
+}
+
 function buildDoctorDiagnosis(model: PiModel): string {
   const lines: string[] = [];
   lines.push(`Provider: ${model.provider}`);
@@ -1848,6 +2813,15 @@ function buildDoctorDiagnosis(model: PiModel): string {
     lines.push("ℹ️ Compat check not applicable for this model.");
   }
 
+  // ── Router/channel diagnostics ──
+  const routerNotes = describeRouterChannelDiagnostics(model);
+  if (routerNotes.length > 0) {
+    lines.push("");
+    for (const note of routerNotes) {
+      lines.push(note);
+    }
+  }
+
   // ── Integrity diagnostics ──
   if (lastPromptIntegrityWarningAt > 0) {
     const ago = Date.now() - lastPromptIntegrityWarningAt;
@@ -1870,21 +2844,46 @@ function buildDoctorDiagnosis(model: PiModel): string {
 
 function buildCompatDiagnosis(model: PiModel): string | undefined {
   const missing = describeMissingOpenAICompatibleProxyCompat(model);
-  if (missing.length === 0) return undefined;
+  const routerNotes = describeRouterChannelDiagnostics(model);
+
+  if (missing.length === 0 && routerNotes.length === 0) return undefined;
 
   const key = modelKey(model);
-  const slashIdx = key.indexOf("/");
-  const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
-  const suggestion = Object.fromEntries(missing.map((f) => [f, true]));
-  const modelsJsonPath = getModelsJsonDisplayPath();
-  return (
-    `Active model: ${key}\n` +
-    `Missing: ${missing.join(", ")}\n\n` +
-    `Edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat` +
-    ` (at the same level as baseUrl/api/apiKey/models) and add:\n` +
-    `${JSON.stringify(suggestion, null, 2)}\n\n` +
-    `Only enable if your endpoint supports them.`
-  );
+  const lines: string[] = [];
+
+  if (missing.length > 0) {
+    const slashIdx = key.indexOf("/");
+    const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
+    const suggestion = Object.fromEntries(missing.map((f) => [f, true]));
+    const modelsJsonPath = getModelsJsonDisplayPath();
+    lines.push(`Active model: ${key}`);
+    lines.push(`Missing: ${missing.join(", ")}`);
+    lines.push("");
+    lines.push(`Edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat`);
+    lines.push(`(at the same level as baseUrl/api/apiKey/models) and add:`);
+    lines.push(JSON.stringify(suggestion, null, 2));
+    lines.push("");
+    lines.push(`Only enable if your endpoint supports them.`);
+  }
+
+  // When compat is fully configured but router notes exist, prefix the status.
+  if (routerNotes.length > 0 && missing.length === 0) {
+    if (isCompatCheckApplicable(model)) {
+      lines.push("✅ Compat fully configured.");
+    } else {
+      lines.push("ℹ️ Compat check not applicable for this model.");
+    }
+    lines.push("");
+  }
+
+  if (routerNotes.length > 0) {
+    if (missing.length > 0) lines.push("");
+    for (const note of routerNotes) {
+      lines.push(note);
+    }
+  }
+
+  return lines.join("\n");
 }
 
 // Internal helpers exported only so the task verification script
@@ -1960,6 +2959,68 @@ export const __internals_for_tests = {
   isJambaLikeAssistantMessage,
   isSolarLikeModel,
   isSolarLikeAssistantMessage,
+  // New OpenAI-compatible model detection (batch 3, 12 families)
+  isPerplexityLikeModel,
+  isPerplexityLikeAssistantMessage,
+  isNovaLikeModel,
+  isNovaLikeAssistantMessage,
+  isRekaLikeModel,
+  isRekaLikeAssistantMessage,
+  isFalconLikeModel,
+  isFalconLikeAssistantMessage,
+  isDbrxLikeModel,
+  isDbrxLikeAssistantMessage,
+  isMptLikeModel,
+  isMptLikeAssistantMessage,
+  isStableLMLikeModel,
+  isStableLMLikeAssistantMessage,
+  isAquilaLikeModel,
+  isAquilaLikeAssistantMessage,
+  isExaoneLikeModel,
+  isExaoneLikeAssistantMessage,
+  isHyperCLOVALikeModel,
+  isHyperCLOVALikeAssistantMessage,
+  isLuminousLikeModel,
+  isLuminousLikeAssistantMessage,
+  isHermesLikeModel,
+  isHermesLikeAssistantMessage,
+  // More OpenAI-compatible model detection (batch 4, 18 families)
+  isGraniteLikeModel,
+  isGraniteLikeAssistantMessage,
+  isArcticLikeModel,
+  isArcticLikeAssistantMessage,
+  isPanguLikeModel,
+  isPanguLikeAssistantMessage,
+  isSenseNovaLikeModel,
+  isSenseNovaLikeAssistantMessage,
+  isZhinaoLikeModel,
+  isZhinaoLikeAssistantMessage,
+  isMiniCPMLikeModel,
+  isMiniCPMLikeAssistantMessage,
+  isXVerseLikeModel,
+  isXVerseLikeAssistantMessage,
+  isOrionLikeModel,
+  isOrionLikeAssistantMessage,
+  isOpenChatLikeModel,
+  isOpenChatLikeAssistantMessage,
+  isVicunaLikeModel,
+  isVicunaLikeAssistantMessage,
+  isWizardLikeModel,
+  isWizardLikeAssistantMessage,
+  isZephyrLikeModel,
+  isZephyrLikeAssistantMessage,
+  isDolphinLikeModel,
+  isDolphinLikeAssistantMessage,
+  isOpenOrcaLikeModel,
+  isOpenOrcaLikeAssistantMessage,
+  isStarlingLikeModel,
+  isStarlingLikeAssistantMessage,
+  isBloomLikeModel,
+  isBloomLikeAssistantMessage,
+  isRwkvLikeModel,
+  isRwkvLikeAssistantMessage,
+  isAyaLikeModel,
+  isAyaLikeAssistantMessage,
   buildOpenAIProxyCompatWarningText,
   getModelIdNameTokenValues,
   getAssistantMessageModelTokenValues,
@@ -1973,6 +3034,7 @@ export const __internals_for_tests = {
   isCompatCheckApplicable,
   buildDoctorDiagnosis,
   buildCompatDiagnosis,
+  describeRouterChannelDiagnostics,
   // Cache stats helpers (module-level, usable from verify script)
   addUsageToCacheStats,
   formatCacheStats,