cartethyia 2.7.8 → 2.8.0

package/src/providers/operations/account-tier.ts

@@ -0,0 +1,66 @@
+/**
+ * Account tier derivation from the plan string the quota collector reported.
+ *
+ * The plan string (`provider_accounts.quota_plan`) is a raw, per-provider
+ * label; this module normalizes it to the three-tier taxonomy the cooldown
+ * rules consume (`free | paid | pro | null`, D14). It is a pure function of
+ * the provider id and the plan text — no database access, no state.
+ *
+ * The mapping is deliberately conservative, following the same posture as
+ * `plan-gate.ts`: a tier is only claimed when the string proves it. "free"
+ * requires the shared free marker set (exported there), "pro" requires a
+ * team/enterprise/org signal, and "paid" is only assigned for providers whose
+ * plan strings are evidenced (Trae, the buddy family, Cursor). Everything else
+ * — an unknown provider, an unrecognized plan, a `null` plan — resolves to
+ * `null`, which keeps the legacy behavior intact (unknown tier ⇒ no rule
+ * applies ⇒ the old constants drive the cooldown).
+ */
+
+import { FREE_PLAN_MARKERS } from "../../transport/routing/plan-gate";
+import { BUDDY_PROVIDER_IDS } from "../provider-metadata";
+import { QODER_CHECKIN_PROVIDER_IDS } from "../integrations/qoder/qoder-checkin";
+import { TRAE_PROVIDER_IDS } from "../integrations/trae/trae-realm";
+
+/** The three-tier taxonomy for cooldown rules. `null` = unknown. */
+export type AccountTier = "free" | "paid" | "pro" | null;
+
+/** Team/enterprise/org signals that prove a "pro" tier. */
+const PRO_PLAN_MARKERS: readonly string[] = ["team", "enterprise", "org", "pro"];
+
+/**
+ * Maps a provider's plan string to a tier.
+ *
+ * `providerId` is normalized case-insensitively; a `null`/empty plan is
+ * unknown (`null`). The "free" check runs before any provider branch because a
+ * proven-free label is the strongest signal (e.g. CodeBuddy's
+ * `personal_free_user`, Trae's `"Free Plan Subscription"`).
+ */
+export function mapPlanToTier(providerId: string, plan: string | null): AccountTier {
+  const lower = (plan ?? "").trim().toLowerCase();
+  if (lower.length === 0) return null;
+  // Free is only claimed when the string proves it — the same marker set the
+  // routing plan-gate uses (imported, not copied), so the two cannot disagree
+  // about an account.
+  if (FREE_PLAN_MARKERS.some((marker) => lower.includes(marker))) return "free";
+
+  if ((QODER_CHECKIN_PROVIDER_IDS as readonly string[]).includes(providerId.toLowerCase())) {
+    // Qoder's `userType` is `personal_standard` by default; team/enterprise/
+    // org suffixes prove a higher tier. `personal_standard` itself is not
+    // verified against the taxonomy, so it stays unknown rather than guessed.
+    if (PRO_PLAN_MARKERS.some((marker) => lower.includes(marker))) return "pro";
+    return null;
+  }
+
+  if (BUDDY_PROVIDER_IDS.has(providerId.toLowerCase())) {
+    if (lower.includes("enterprise") || lower.includes("team")) return "pro";
+    return "paid";
+  }
+
+  // Trae (paid plans other than the free subscription) and Cursor (a non-free
+  // `membershipType`/`planName` is a paying plan by construction).
+  if (TRAE_PROVIDER_IDS.has(providerId.toLowerCase())) return "paid";
+  if (providerId.toLowerCase() === "cursor") return "paid";
+
+  // Unknown provider: no claim. Legacy behavior applies.
+  return null;
+}

package/src/providers/operations/client-version-resolver.ts

@@ -11,7 +11,7 @@
  * Discovery is owned by the background client-version monitor. Request paths
  * only call the synchronous `get`/`snapshot` accessors and never fetch.
  */
-import { getCachedVersion, resetVersionCacheForTesting } from "./provider-version-cache";
+import { getCachedVersion, resetVersionCacheForTesting } from "./provider-caches";
 import type { OutboundFetch } from "../provider-contracts";
 import { composeAbortSignal } from "../authentication/oauth-flow-store";
 

package/src/providers/operations/client-versions.ts

@@ -16,15 +16,6 @@ import {
   buildGrokShellUserAgent,
 } from "./cli-platform";
 
-async function qoderVersion(response: Response): Promise<string | null> {
-  try {
-    const parsed = (await response.json()) as { version?: unknown };
-    return isSemverish(parsed.version) ? parsed.version.trim() : null;
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Newest Trae IDE version from the official changelog.
  *
@@ -67,17 +58,12 @@ async function traeVersion(response: Response): Promise<string | null> {
   }
 }
 
-async function clineClientVersion(response: Response): Promise<string | null> {
-  const data = (await response.json()) as { version?: unknown };
-  return isSemverish(data.version) ? data.version.trim() : null;
-}
-
 /**
  * Newest Cursor build from the official download API, as the IDE's own header
  * spells it.
  *
  * Cursor's `x-cursor-client-version` is not the IDE semver on its own: the wire
- * value is `cli-<version>-<sha7>` (observed live as `cli-2026.10.19-6bbf2c4`).
+ * value is `cli-<version>-<sha7>` (observed live as `cli-2026.11.05-86047df`).
  * The download API is the only source that returns both halves — `version` and
  * `commitSha` — so they are joined here rather than guessed. A semver alone
  * would be a different identity than the one the IDE sends.
@@ -95,41 +81,6 @@ async function cursorVersion(response: Response): Promise<string | null> {
   }
 }
 
-async function clineSdkVersion(response: Response): Promise<string | null> {
-  const data = (await response.json()) as {
-    version?: unknown;
-    "dist-tags"?: { latest?: unknown };
-  };
-  const candidate = data.version ?? data["dist-tags"]?.latest;
-  return isSemverish(candidate) ? candidate.trim() : null;
-}
-
-async function kimiVersion(response: Response): Promise<string | null> {
-  const data = (await response.json()) as { info?: { version?: unknown } };
-  return isSemverish(data.info?.version) ? data.info.version.trim() : null;
-}
-
-async function workbuddyDesktopVersion(response: Response): Promise<string | null> {
-  try {
-    const data = (await response.json()) as { version?: unknown; productVersion?: unknown };
-    const candidate = data.productVersion ?? data.version;
-    return typeof candidate === "string" && /^\d+\.\d+\.\d+(?:\.\d+)?(?:[-+][\w.-]+)?$/.test(candidate.trim())
-      ? candidate.trim()
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-async function kiroCaskVersion(response: Response): Promise<string | null> {
-  try {
-    const data = (await response.json()) as { version?: unknown };
-    return isSemverish(data.version) ? data.version.trim() : null;
-  } catch {
-    return null;
-  }
-}
-
 async function codeBuddyCnVersion(response: Response): Promise<string | null> {
   try {
     const data = (await response.json()) as { version?: unknown };
@@ -232,7 +183,7 @@ const KIRO_NODE_VERSION = "24.18.0";
 export const VERSION_SOURCES = {
   antigravity: {
     key: "antigravity",
-    fallback: "2.28.2",
+    fallback: "2.29.0",
     sources: [
       {
         url: "https://antigravity-hub-auto-updater-974169037036.us-central1.run.app/manifest/latest-arm64-mac.yml",
@@ -248,12 +199,7 @@ export const VERSION_SOURCES = {
     // `@qoder-ai/qodercli/latest`) may report a newer CLI, but the CLI and
     // IDE are different products — the chat surface identity is the IDE's.
     fallback: "1.1.80",
-    sources: [
-      {
-        url: "https://registry.npmjs.org/@qoder-ai/qodercli/latest",
-        extract: qoderVersion,
-      },
-    ],
+    sources: [{ url: "https://registry.npmjs.org/@qoder-ai/qodercli/latest" }],
   },
   opencode: {
     key: "opencode",
@@ -261,21 +207,21 @@ export const VERSION_SOURCES = {
     // under `@opencode/cli`, and this feed is what its own installer reads.
     // Fallback = the current latest release; raise it whenever the package
     // moves so a cold process does not present a stale client build.
-    fallback: "2.2.5",
+    fallback: "2.2.6",
     minVersion: "2.0.0",
     sources: [{ url: "https://opencode.ai/update/api/latest/cli/npm" }],
   },
   commandcode: {
     key: "commandcode",
-    // npm `command-code` latest as of 2026-10-30. The CLI sends this as
+    // npm `command-code` latest as of 2026-11-07. The CLI sends this as
     // `x-command-code-version`, so a stale fallback presents a client build
     // the upstream no longer ships — raise it whenever the package moves.
-    fallback: "1.88.2",
+    fallback: "1.88.5",
     sources: [{ url: "https://registry.npmjs.org/command-code/latest" }],
   },
   grok: {
     key: "grok",
-    fallback: "1.0.70",
+    fallback: "1.0.77",
     sources: [
       { url: "https://storage.googleapis.com/grok-build-public-artifacts/cli/stable" },
       { url: "https://registry.npmjs.org/@xai-official/grok/latest" },
@@ -286,85 +232,45 @@ export const VERSION_SOURCES = {
     fallback: "4.1.26",
     minVersion: "4.1.23",
     sources: [
-      {
-        url: "https://raw.githubusercontent.com/cline/cline/main/apps/vscode/package.json",
-        extract: clineClientVersion,
-      },
+      { url: "https://raw.githubusercontent.com/cline/cline/main/apps/vscode/package.json" },
     ],
   },
   clineSdk: {
     key: "cline-sdk",
     fallback: "0.2.0",
-    sources: [{ url: "https://registry.npmjs.org/@cline/sdk/latest", extract: clineSdkVersion }],
+    sources: [{ url: "https://registry.npmjs.org/@cline/sdk/latest" }],
   },
   clineCli: {
     key: "cline-cli",
     fallback: "3.0.74",
-    sources: [{ url: "https://registry.npmjs.org/cline/latest", extract: clineSdkVersion }],
+    sources: [{ url: "https://registry.npmjs.org/cline/latest" }],
   },
   codex: {
     key: "codex",
-    fallback: "0.166.0",
+    fallback: "0.167.0",
     sources: [{ url: "https://registry.npmjs.org/@openai/codex/latest" }],
   },
-  workbuddyClient: {
-    key: "workbuddy-client",
-    fallback: "5.9.4.42593613",
-    sources: [
-      {
-        url: "https://www.workbuddy.ai/v2/update?platform=workbuddy-win32-x64-user",
-        extract: workbuddyDesktopVersion,
-      },
-      {
-        url: "https://www.workbuddy.ai/v2/update?platform=workbuddy-darwin-arm64",
-        extract: workbuddyDesktopVersion,
-      },
-    ],
-  },
-  workbuddyCnClient: {
-    key: "workbuddy-cn-client",
-    fallback: "5.9.3.42398134",
-    sources: [
-      {
-        url: "https://www.workbuddy.cn/v2/update?platform=workbuddy-win32-x64-user",
-        extract: workbuddyDesktopVersion,
-      },
-      {
-        url: "https://www.workbuddy.cn/v2/update?platform=workbuddy-darwin-arm64",
-        extract: workbuddyDesktopVersion,
-      },
-    ],
-  },
-  workbuddyCli: {
-    key: "workbuddy",
-    fallback: "2.178.1",
-    sources: [
-      { url: "https://registry.npmjs.org/@tencent-ai/codebuddy-code/latest" },
-      { url: "https://registry.npmmirror.com/@tencent-ai/codebuddy-code/latest" },
-    ],
-  },
   kimiCli: {
     key: "kimi-cli",
     fallback: "1.52.0",
-    sources: [{ url: "https://pypi.org/pypi/kimi-cli/json", extract: kimiVersion }],
+    sources: [{ url: "https://pypi.org/pypi/kimi-cli/json" }],
   },
   kiro: {
     key: "kiro",
-    fallback: "1.4.62",
+    fallback: "1.4.121",
     sources: [
       {
         // Kiro's downloads page exposes no stable version string. Homebrew
         // tracks the official installer URL and exposes its version as JSON;
         // keep the product page parser as a fallback.
         url: "https://formulae.brew.sh/api/cask/kiro.json",
-        extract: kiroCaskVersion,
       },
       { url: "https://kiro.dev/downloads/", extract: kiroVersion },
     ],
   },
   codebuddy: {
     key: "codebuddy",
-    fallback: "2.178.1",
+    fallback: "2.181.0",
     sources: [
       { url: "https://registry.npmjs.org/@tencent-ai/codebuddy-code/latest" },
       { url: "https://registry.npmmirror.com/@tencent-ai/codebuddy-code/latest" },
@@ -372,7 +278,7 @@ export const VERSION_SOURCES = {
   },
   codebuddyCn: {
     key: "codebuddy-cn",
-    fallback: "4.12.2.41207131",
+    fallback: "4.12.3.42658816",
     sources: [
       {
         // Official CN builds are listed by Homebrew's maintained cask feed;
@@ -387,7 +293,7 @@ export const VERSION_SOURCES = {
     // Current `@anthropic-ai/claude-code` release, so the billing
     // `cc_version=` suffix and the `claude-cli/` User-Agent stay on what
     // upstream ships.
-    fallback: "2.1.314",
+    fallback: "2.1.319",
     sources: [{ url: "https://registry.npmjs.org/@anthropic-ai/claude-code/latest" }],
   },
   claudeSdk: {
@@ -404,7 +310,7 @@ export const VERSION_SOURCES = {
   },
   github: {
     key: "github-copilot-chat",
-    fallback: "0.43.0",
+    fallback: "0.43.2026040705",
     sources: [
       {
         url: "https://api.github.com/repos/microsoft/vscode-copilot-chat/releases/latest",
@@ -414,7 +320,7 @@ export const VERSION_SOURCES = {
   },
   kilo: {
     key: "kilo-code",
-    fallback: "7.8.25",
+    fallback: "7.8.27",
     sources: [{ url: "https://open-vsx.org/api/kilocode/kilo-code" }],
   },
   muse: {
@@ -436,12 +342,27 @@ export const VERSION_SOURCES = {
       },
     ],
   },
+  freepi: {
+    key: "freepi",
+    // The free-pi CLI version — the `x-client-version` the gateway reports.
+    // Fallback = the unpacked 0.6.14 bundle; npm discovery replaces it.
+    fallback: "0.6.14",
+    sources: [{ url: "https://registry.npmjs.org/free-pi-cli/latest" }],
+  },
+  perch: {
+    key: "perch",
+    // The official Perch CLI, spawned by the adapter for hosted inference.
+    fallback: "2.4.125",
+    sources: [{ url: "https://registry.npmjs.org/perchai-cli/latest" }],
+  },
   cursor: {
     key: "cursor",
-    // Fallback = the last observed wire version. Discovery replaces it within
-    // one monitor tick; it is only what a cold process sends before the first
-    // successful fetch.
-    fallback: "cli-3.27.22-b1aa50c",
+    // Fallback = the last observed wire version (CLI ~2026.11.07-306d153).
+    // Discovery replaces it within one monitor tick; it is only what a cold
+    // process sends before the first successful fetch. Kept equal to
+    // `FALLBACK_CLIENT_VERSION` in the cursor adapter so the badge and the
+    // request header always send one identity.
+    fallback: "cli-3.29.9-306d153",
     sources: [
       {
         url: "https://cursor.com/api/download?platform=win32-x64-user&releaseTrack=stable",
@@ -455,7 +376,7 @@ export const VERSION_SOURCES = {
     // comment this replaced claimed no semver existed and pinned a date tag
     // (`v2026.9.24`) as the version — a tag, not a release, and not the
     // identity the client sends.
-    fallback: "0.22.5",
+    fallback: "0.23.0",
     sources: [
       {
         url: "https://api.github.com/repos/NousResearch/hermes-agent/releases/latest",
@@ -465,7 +386,7 @@ export const VERSION_SOURCES = {
   },
   zcode: {
     key: "zcode",
-    fallback: "3.14.3",
+    fallback: "3.17.2",
     sources: [
       {
         url: "https://api.github.com/repos/zai-org/ZCode/releases/latest",
@@ -480,6 +401,8 @@ const resolvers = {
   qoder: createClientVersionResolver({ ...VERSION_SOURCES.qoder, client: "qoder" }),
   hermes: createClientVersionResolver({ ...VERSION_SOURCES.hermes, client: "hermes" }),
   trae: createClientVersionResolver({ ...VERSION_SOURCES.trae, client: "trae" }),
+  freepi: createClientVersionResolver({ ...VERSION_SOURCES.freepi, client: "freepi" }),
+  perch: createClientVersionResolver({ ...VERSION_SOURCES.perch, client: "perch" }),
   cursor: createClientVersionResolver({ ...VERSION_SOURCES.cursor, client: "cursor" }),
   opencode: createClientVersionResolver({ ...VERSION_SOURCES.opencode, client: "opencode" }),
   commandcode: createClientVersionResolver({ ...VERSION_SOURCES.commandcode, client: "command-code" }),
@@ -488,9 +411,6 @@ const resolvers = {
   clineSdk: createClientVersionResolver({ ...VERSION_SOURCES.clineSdk, client: "cline-sdk" }),
   clineCli: createClientVersionResolver({ ...VERSION_SOURCES.clineCli, client: "cline-cli" }),
   codex: createClientVersionResolver({ ...VERSION_SOURCES.codex, client: "codex" }),
-  workbuddyClient: createClientVersionResolver({ ...VERSION_SOURCES.workbuddyClient, client: "workbuddy" }),
-  workbuddyCnClient: createClientVersionResolver({ ...VERSION_SOURCES.workbuddyCnClient, client: "workbuddy-cn" }),
-  workbuddyCli: createClientVersionResolver({ ...VERSION_SOURCES.workbuddyCli, client: "codebuddy" }),
   kimiCli: createClientVersionResolver({ ...VERSION_SOURCES.kimiCli, client: "kimi" }),
   codebuddy: createClientVersionResolver({ ...VERSION_SOURCES.codebuddy, client: "codebuddy" }),
   codebuddyCn: createClientVersionResolver({ ...VERSION_SOURCES.codebuddyCn, client: "codebuddy" }),
@@ -520,8 +440,6 @@ const PROVIDER_VERSION_RESOLVERS: Readonly<Record<string, ClientVersionResolver>
   traecn: resolvers.trae,
   cursor: resolvers.cursor,
   commandcode: resolvers.commandcode,
-  workbuddy: resolvers.workbuddyClient,
-  workbuddycn: resolvers.workbuddyCnClient,
   cb: resolvers.codebuddy,
   cbcn: resolvers.codebuddyCn,
   kimi: resolvers.kimiCli,
@@ -641,37 +559,11 @@ export const _resetClineCliVersionCache = accessor("clineCli").reset;
 
 export const getCodexVersion = accessor("codex").get;
 
-export const getWorkBuddyClientVersion = accessor("workbuddyClient").get;
-export const getWorkBuddyCnClientVersion = accessor("workbuddyCnClient").get;
-export const getWorkBuddyCliVersion = accessor("workbuddyCli").get;
-
-export function buildWorkBuddyUserAgent(
-  identity = "WB",
-  clientVersion = getWorkBuddyClientVersion(),
-  cliVersion = getWorkBuddyCliVersion(),
-): string {
-  // 1:1 with codebuddy2api. The CLI profile is `CLI/<v> CodeBuddy/<v>` and the
-  // WorkBuddy profile is `WorkBuddy/<wb> workbuddy-ai/<wb> CLI/<cli>`, which
-  // sends NO SDK headers — two separate profiles, not one string with a switch.
-  // Whether SDK headers ride along is decided by `workbuddyHeaders`, not here, so
-  // this builder only decides the UA text.
-  //
-  // The second token is the wire spelling `workbuddy-ai`, NOT the display
-  // brand `WorkBuddy AI`. This is what an official client actually sends; the
-  // product is branded with a space in the UI and in docs, and copying that
-  // branding into the header produced a UA no real client emits — which the
-  // intl gateway answers with 403 `11140`, the same refusal it gives a
-  // wrong-brand header. Product name ≠ wire token.
-  if (identity === "CLI") return `CLI/${cliVersion} CodeBuddy/${cliVersion}`;
-  return `WorkBuddy/${clientVersion} workbuddy-ai/${clientVersion} CLI/${cliVersion}`;
-}
-
-export const _resetWorkBuddyCnClientVersionCache = accessor("workbuddyCnClient").reset;
-
 export const getKimiCliVersion = accessor("kimiCli").get;
 
 export const getCodeBuddyVersion = accessor("codebuddy").get;
 export const getCodeBuddyCnVersion = accessor("codebuddyCn").get;
+
 /**
  * The CodeBuddy User-Agent.
  *

package/src/providers/operations/cooldown-rules.ts

@@ -0,0 +1,56 @@
+/**
+ * Static in-code registry of provider × category × tier cooldown rules (D19).
+ *
+ * The registry ships empty by default: before a rule is filled in, behavior is
+ * byte-identical to the old hardcoded constants. Rules are keyed by
+ * `(providerId, category, tier)` and, when present, replace the provider's old
+ * cooldown constant for that combination — they sit between the provider-stated
+ * window (which always wins, D18) and the old constant/env fallback.
+ *
+ * The initial content is the example from the approved proposal (part 03):
+ * Trae's daily-quota verdict (`model_unreachable`, upstream 4008) cools a free
+ * account for a full day and a paid/pro account for 15 minutes (D17 — `paid`
+ * never gets `0`, which would hammer the upstream on a wrong verdict).
+ */
+import type { AccountErrorCategory } from "./account-error-classification";
+import type { AccountTier } from "./account-tier";
+
+export type CooldownRuleKey = {
+  readonly providerId: string;
+  readonly category: AccountErrorCategory;
+  readonly tier: AccountTier;
+};
+
+type TierRules = Partial<Record<NonNullable<AccountTier>, number>>;
+type CategoryRules = Partial<Record<AccountErrorCategory, TierRules>>;
+type ProviderRules = Record<string, CategoryRules>;
+
+const DAY = 24 * 60 * 60 * 1000;
+const MINUTE = 60 * 1000;
+
+const TRAE_RULES: CategoryRules = {
+  model_unreachable: {
+    free: DAY,
+    paid: 15 * MINUTE,
+    pro: 15 * MINUTE,
+  },
+};
+
+const COOLDOWN_RULES: ProviderRules = {
+  trae: TRAE_RULES,
+  // Trae CN is the same upstream product under a second realm id — the
+  // classifier already treats the two identically, so the rules alias.
+  traecn: TRAE_RULES,
+};
+
+/**
+ * Resolves a cooldown rule for `(providerId, category, tier)`.
+ *
+ * Returns `undefined` when no rule exists — for an unknown provider, an
+ * unstored category, or an unknown tier — which is the signal to keep the old
+ * constant/fallback behavior.
+ */
+export function resolveCooldownRule(key: CooldownRuleKey): number | undefined {
+  if (key.tier === null || key.tier === undefined) return undefined;
+  return COOLDOWN_RULES[key.providerId.toLowerCase()]?.[key.category]?.[key.tier];
+}

package/src/providers/operations/{model-catalog-cache.ts → provider-caches.ts}

@@ -1,16 +1,17 @@
 /**
- * Process-lifetime model-catalog cache.
- *
- * `bundledModelCatalog` is called during startup seeding and again whenever a
- * caller rebuilds the routing/console catalog. Caching the loader *promise*
- * (not just the resolved value) makes concurrent and repeated calls for one
- * provider share a single load, and lets the dynamic catalog imports run once
- * per process. A rejected load is evicted so a later call can retry.
+ * In-process caches for model catalogs, model discovery, and client/provider versions.
  */
+
 import type { ModelDefinition } from "../provider-model-definition";
 import { trackModelCatalogLoad } from "../../observability/performance-metrics";
 import { resolveRedisClient } from "../../persistence/redis";
 import { cachedRead } from "../../console/shared/read-through-cache";
+import { TtlCacheFamily } from "../../persistence/ttl-cache";
+import { retryWithBackoff } from "../../network/retry";
+
+/* -------------------------------------------------------------------------- */
+/* 1. Model Catalog Cache                                                     */
+/* -------------------------------------------------------------------------- */
 
 /**
  * Provider entries retained before the least-recently-used catalog is evicted.
@@ -37,8 +38,7 @@ const catalogCache = new Map<string, Promise<readonly ModelDefinition[]>>();
 /**
  * Evicts the least-recently-used provider before inserting a new one once the
  * cache is at its bound. `Map` preserves insertion order and every cache hit
- * re-inserts its entry at the tail, so the head is the LRU key. Without this
- * bound the process-lifetime cache pinned one catalog per provider forever.
+ * re-inserts its entry at the tail, so the head is the LRU key.
  */
 function evictLeastRecentlyUsedCatalog(maxEntries: number): void {
   if (catalogCache.size < maxEntries) return;
@@ -87,13 +87,65 @@ export function resetModelCatalogCacheForTesting(): void {
   catalogCache.clear();
 }
 
-/**
- * Live entry count, for the `/metrics` gauge.
- *
- * Exported so a rebuild that saturates the cap is visible from outside the
- * process: before this, every in-process cache except the quota tier was
- * invisible, and growth could only be found with a heap dump.
- */
+/** Live entry count, for the `/metrics` gauge. */
 export function modelCatalogCacheSize(): number {
   return catalogCache.size;
 }
+
+/* -------------------------------------------------------------------------- */
+/* 2. Model Discovery Cache                                                   */
+/* -------------------------------------------------------------------------- */
+
+const MODEL_DISCOVERY_CACHE_TTL_MS = 10 * 60 * 1000;
+const discoveryCaches = new TtlCacheFamily<readonly ModelDefinition[]>({
+  defaultTtlMs: MODEL_DISCOVERY_CACHE_TTL_MS,
+});
+
+export interface CachedModelDiscoveryOptions {
+  readonly ttlMs?: number;
+}
+
+/** Returns cached models, retrying null/empty loads on the next call. */
+export async function getCachedModelDiscovery(
+  key: string,
+  loader: () => Promise<readonly ModelDefinition[] | null>,
+  options: CachedModelDiscoveryOptions = {},
+): Promise<readonly ModelDefinition[] | null> {
+  return discoveryCaches.for(options.ttlMs).load(key, loader, {
+    namespace: "model-discovery",
+    shouldCache: (models) => models.length > 0,
+  });
+}
+
+/** Drops all cached discoveries. Test-only. */
+export function resetModelDiscoveryCacheForTesting(): void {
+  discoveryCaches.clear();
+}
+
+/* -------------------------------------------------------------------------- */
+/* 3. Provider Version Cache                                                  */
+/* -------------------------------------------------------------------------- */
+
+const VERSION_CACHE_TTL_MS = 5 * 60 * 1000;
+const versionCaches = new TtlCacheFamily<string>({ defaultTtlMs: VERSION_CACHE_TTL_MS });
+
+export interface CachedVersionOptions {
+  readonly ttlMs?: number;
+  readonly maxRetries?: number;
+}
+
+export async function getCachedVersion(
+  key: string,
+  loader: () => Promise<string | null>,
+  options: CachedVersionOptions = {},
+): Promise<string | null> {
+  const loadWithRetry = () => retryWithBackoff(loader, { maxRetries: options.maxRetries ?? 2 });
+  return versionCaches.for(options.ttlMs).load(key, loadWithRetry, {
+    namespace: "provider-version",
+  });
+}
+
+/** Drops all cached versions. Test-only. */
+export function resetVersionCacheForTesting(): void {
+  versionCaches.clear();
+}

package/src/providers/operations/provider-catalog-seeder.ts

@@ -60,6 +60,9 @@ export async function seedBundledModels(
           // states the tier, so the flag is carried rather than derived.
           freeTier: definition.freeTier ?? null,
           dialect: definition.dialect ?? null,
+          // Display-only: a static catalog that declares no warnings clears any
+          // stale value on the next boot rather than leaving an old banner.
+          warningMetadata: definition.warnings ?? null,
           source: "builtin",
           sourceUpdatedAt: now,
           enabled: true,
@@ -90,6 +93,7 @@ export async function seedBundledModels(
       proOnly: sql`excluded.pro_only`,
       freeTier: sql`excluded.free_tier`,
       dialect: sql`excluded.dialect`,
+      warningMetadata: sql`excluded.warning_metadata`,
       source: sql`'builtin'`,
       sourceUpdatedAt: sql`excluded.source_updated_at`,
     },

package/src/providers/operations/provider-catalog-service.ts

@@ -10,7 +10,7 @@ import { ProviderRegistry } from "../provider-registry";
 import { OpenAICompatibleAdapter } from "../adapters/compatible-adapter";
 import { resolveByokWireProfile } from "./byok-wire-profile";
 import { BUNDLED_PROVIDER_MODULES } from "../default-registry";
-import { getCachedModels } from "./model-catalog-cache";
+import { getCachedModels } from "./provider-caches";
 import { seedBundledModels } from "./provider-catalog-seeder";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import { providers } from "../../persistence/schema";