@hyav/pi-provider 0.1.7 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 This file is the authoritative user-facing release history for `@hyav/pi-provider`.
 
+## 0.2.0 - 2026-09-06
+
+- Add Pi catalog fallback based on `@earendil-works/pi-ai` built-in models, scoped to original manufacturer providers (`anthropic`, `openai`, `google`, `deepseek`, `mistral`, `xai`, `minimax`, `minimax-cn`, `moonshotai`, `moonshotai-cn`, `kimi-coding`, `zai`, `zai-coding-cn`, `xiaomi`, and `ant-ling`), strictly excluding OpenRouter, third-party proxies, aggregators, and token plans.
+- Supplement registered provider models with missing fields (`cost`, `contextWindow`, `maxTokens`, `input` modalities, `reasoning`, `thinkingLevelMap`, and `compat`) using deterministic matching and field-level provenance (`provider`, `pi`, `mixed`, `default`, `normalized`); support disabling fallback per adapter via `usePiModelMetaFallback: false`.
+- Establish dynamic provider adapter persistence contract: dynamic adapters must persist raw model drafts instead of normalized default models to prevent defaulted capabilities from suppressing manufacturer metadata in the Pi catalog fallback; detect and invalidate legacy normalized snapshots.
+- Add a copyable Ant Digital MaaS Provider and Preflight example with authenticated dynamic discovery, bounded catalog parsing, raw-draft cache migration, timeout handling, and model matching.
+- Prevent the OpenRouter Preflight adapter from reporting a successful authentication check when no usable credential is resolved.
+- Refactor `/status` reporting: compress `Catalog:`, `Health:`, and `Account:` to compact single lines, merge `Reasoning:` and `Thinking levels:` into a single line, and display field-level provenance.
+- Remove OpenRouter generic model metadata, pricing completion, and cache mechanisms (`openrouter-model-metadata.json`, `fetchOfficialModelMetadata()`, `fetchOfficialPricing()`, `applyOfficialModelMetadata()`, `applyOfficialModelCosts()`, `parseOpenRouterModels()`, `parseOpenRouterPricing()`, `findOfficialMeta()`, `findOfficialCost()`, `getDefaultOpenRouterMetadataCachePath()`, and `OPENROUTER_MODELS_URL`); OpenRouter as a native Pi provider with its own status/preflight adapters remains fully supported.
+- Remove benchmark quality runtime, adapters, caching, and diagnostics (`QualityManager`, Artificial Analysis, LiveBench, Agent Arena, `/status quality`, `ARTIFICIAL_ANALYSIS_API_KEY`, and quality cache directories).
+
+## 0.1.8 - 2026-09-01
+
+- Make Charm Hyper model catalogs online-only: use the last successful online snapshot when refresh is unavailable and an empty catalog when no snapshot exists; remove package-maintained static model, pricing, and model-specific capability fallbacks.
+- Skip malformed individual Charm Hyper models while retaining valid entries, and use Provider metadata before OpenRouter metadata when filling model fields.
+- Add a public model-catalog lifecycle helper for cached snapshot restoration, TTL checks, generation-guarded publication, persistence fallback, complete live replacement, and failure retention; migrate Charm Hyper to it.
+- Share one model-catalog discovery request across concurrent callers with different cancellation signals, while keeping caller cancellation and generation-guarded publication independent.
+- Separate successful-catalog TTL from exponential failure backoff, expose attempt, success, failure-count, and retry diagnostics, and show retry timing in `/status`.
+- Report bounded invalid and duplicate model counts for accepted online catalogs without retaining remote model IDs or payload content.
+- Add accurately named OpenRouter metadata APIs (`fetchOfficialModelMetadata()` and `applyOfficialModelMetadata()`), migrate internal callers, and retain the pricing-named APIs as deprecated compatibility wrappers.
+- Extend field-level provenance to normalized cost and thinking-level maps while keeping `pricing.source` authoritative for known and effective pricing.
+- Normalize partial model costs before applying pricing adjustments so registered model costs and pricing sidecars remain consistent; report fields rewritten at the registration boundary as `normalized`.
+
 ## 0.1.7 - 2026-08-24
 
 - Refresh the active model catalog dynamically on `/status refresh` and `/status check` by delegating to Pi's model registry with forced network revalidation, keeping the displayed model catalog and model counts up to date without requiring `/reload`.

package/README.md

@@ -10,8 +10,8 @@ A provider extension toolkit for [Pi](https://pi.dev). It registers LLM provider
 
 - One Pi Provider Host for registration, status, preflight checks, live checks, and request tuners
 - Provider, status, preflight, and tuner Adapter files discovered by one Pi entrypoint on `/reload`
-- Resilient model catalogs with cached fallback, bounded background refresh, and failure retention
-- Provider-first pricing metadata with optional OpenRouter completion and quality indicators
+- Resilient model catalogs with cached online snapshots, bounded background refresh, and failure retention
+- Provider-first metadata completed by Pi native manufacturer catalog, with deterministic field-level provenance
 - Explicit diagnostics: cached `/status`, free `/status refresh`, and potentially billable `/status check`
 - Built-in integrations for Charm Hyper, DeepSeek, Google Gemini, OpenAI Codex, OpenCode Zen, and OpenCode Go
 - Status/preflight adapters for the native Pi providers Anthropic, GitHub Copilot, OpenRouter, Groq, and xAI
@@ -45,7 +45,7 @@ pi install npm:@hyav/pi-provider
 
 Use `/status refresh` for free endpoint, authentication, catalog, and account checks. Use `/status check` only when you explicitly accept a real model request and possible usage charges.
 
-A dynamic Provider whose API key references environment variables keeps its cached or fallback model catalog and skips network catalog refreshes until those variables or a stored credential are available. This prevents unconfigured Providers from surfacing model-refresh warnings.
+A dynamic Provider whose API key references environment variables keeps its last successful online catalog snapshot and skips network catalog refreshes until those variables or a stored credential are available. Providers without a successful snapshot expose an empty catalog rather than inventing models. This prevents unconfigured Providers from surfacing model-refresh warnings.
 
 ## Common configuration
 
@@ -53,9 +53,9 @@ A dynamic Provider whose API key references environment variables keeps its cach
 |---|---:|---|---|
 | `HYPER_API_KEY` | For Charm Hyper API-key auth | None | Supplies the built-in `charm-hyper` provider credential; OAuth users may use `/login` |
 | `ANTHROPIC_USAGE_URL` | No | `https://claude.ai/api/usage` | Custom Anthropic usage endpoint; default endpoint is subscription OAuth only |
-| `PI_CODING_AGENT_DIR` | No | `~/.pi/agent` | Changes Pi's agent directory; public OpenRouter metadata is cached under `<agent-dir>/extensions/pi-provider/` |
+| `PI_CODING_AGENT_DIR` | No | `~/.pi/agent` | Changes Pi's agent directory |
 
-Programmatic integrations can configure pricing fallback, pricing policies, request timeouts, metadata URLs, and cache paths through `createPiProviderRuntime()` or `createPiProviderHost()`. Programmatic defaults resolve the agent directory from `PI_CODING_AGENT_DIR` (falling back to `~/.pi/agent`) and keep the OpenRouter metadata cache on disk under `<agent-dir>/extensions/pi-provider/`, matching the table above; the Pi entrypoint overrides it with Pi's own resolution. Host packages with a custom capability root can call `createPiProviderExtension({ adapterRoot, dependencies })`. The source definition [`PiProviderDependencies`](core/runtime-config.ts) is authoritative.
+Programmatic integrations can configure pricing policies, request timeouts, and provider options through `createPiProviderRuntime()` or `createPiProviderHost()`. Programmatic defaults resolve the agent directory from `PI_CODING_AGENT_DIR` (falling back to `~/.pi/agent`); the Pi entrypoint overrides it with Pi's own resolution. Host packages with a custom capability root can call `createPiProviderExtension({ adapterRoot, dependencies })`. The source definition [`PiProviderDependencies`](core/runtime-config.ts) is authoritative.
 
 ## Adapter discovery (file-level plug and play)
 
@@ -70,7 +70,7 @@ Built-in Adapters ship inside the package and are always discovered. User Adapte
 ```
 
 
-Add, remove, or modify files there, then run `/reload` to rediscover them without touching the package; edits to existing files are re-read from disk. User Adapters load after built-ins, so a same-ID file overrides the built-in Adapter (the Host keeps the latest registration and warns). `createPiProviderExtension({ adapterRoot })` replaces the default user directory with a custom root; built-ins are always scanned. The built-in Adapters under the package's `providers/`, `status/`, and `preflight/` are reference templates with this exact shape — copy one and customize it (Charm Hyper and `preflight/openai-codex.ts` also use package-private helpers). A complete non-built-in Command Code reference is available in [`examples/command-code`](examples/command-code/).
+Add, remove, or modify files there, then run `/reload` to rediscover them without touching the package; edits to existing files are re-read from disk. User Adapters load after built-ins, so a same-ID file overrides the built-in Adapter (the Host keeps the latest registration and warns). `createPiProviderExtension({ adapterRoot })` replaces the default user directory with a custom root; built-ins are always scanned. The built-in Adapters under the package's `providers/`, `status/`, and `preflight/` are reference templates with this exact shape — copy one and customize it (Charm Hyper and `preflight/openai-codex.ts` also use package-private helpers). Complete non-built-in references are available for [Ant Digital MaaS](examples/maas/) and [Command Code](examples/command-code/).
 
 Adapter files import helpers and types from `@hyav/pi-provider` (aliased inside the loader):
 
@@ -82,7 +82,7 @@ Adapter files must not runtime-import Pi's bundled packages (`@earendil-works/pi
 
 ## Before you use it
 
-`/status` is offline, `/status refresh` performs free remote checks, and `/status check` sends a live model request that may consume quota. Configured credentials are sent only to the corresponding provider endpoints and are omitted from status output.
+`/status` is offline, `/status refresh` performs free remote checks and updates catalog caches, and `/status check` sends a live model request that may consume quota. Configured credentials are sent only to the corresponding provider endpoints and are omitted from status output.
 
 ## License
 

package/README.zh-CN.md

@@ -10,8 +10,8 @@
 
 - 由一个 Pi Provider Host 统一负责注册、Status、Preflight、实时检查和请求 Tuner
 - 由单一 Pi 入口在 `/reload` 时发现 Provider、Status、Preflight 和 Tuner Adapter 文件
-- 通过缓存回退、有界后台刷新和失败保留提供可靠的模型目录
-- 优先采用 Provider 价格元数据，并可由 OpenRouter 补全价格和质量指标
+- 通过缓存在线快照、有界后台刷新和失败保留提供可靠的模型目录
+- 优先采用 Provider 元数据，并由 Pi 原厂模型目录补全价格与能力，具备确定性的字段级来源诊断
 - 显式诊断：缓存 `/status`、免费 `/status refresh` 和可能计费的 `/status check`
 - 内置 Charm Hyper、DeepSeek、Google Gemini、OpenAI Codex、OpenCode Zen 和 OpenCode Go 集成
 - Status/Preflight 适配覆盖 Pi 原生 Provider：Anthropic、GitHub Copilot、OpenRouter、Groq、xAI
@@ -45,7 +45,7 @@ pi install npm:@hyav/pi-provider
 
 使用 `/status refresh` 执行免费的端点、鉴权、目录和账户检查。只有明确接受一次真实模型请求及其可能产生的用量费用时，才使用 `/status check`。
 
-动态 Provider 的 API Key 引用环境变量时，如果这些变量和已存储凭据均未配置，将保留缓存或回退模型目录并跳过网络刷新，避免未配置的 Provider 产生模型目录刷新警告。
+动态 Provider 的 API Key 引用环境变量时，如果这些变量和已存储凭据均未配置，将保留最近一次成功获取的在线目录快照；如果从未成功获取过在线目录，则使用空目录，并跳过网络刷新，避免未配置的 Provider 产生模型目录刷新警告。
 
 ## 常用配置
 
@@ -53,9 +53,9 @@ pi install npm:@hyav/pi-provider
 |---|---:|---|---|
 | `HYPER_API_KEY` | Charm Hyper API Key 鉴权需要 | 无 | 为内置 `charm-hyper` Provider 提供凭据；OAuth 用户可以使用 `/login` |
 | `ANTHROPIC_USAGE_URL` | 否 | `https://claude.ai/api/usage` | 自定义 Anthropic 用量端点；默认端点仅支持订阅 OAuth |
-| `PI_CODING_AGENT_DIR` | 否 | `~/.pi/agent` | 修改 Pi agent 目录；公开 OpenRouter 元数据缓存在 `<agent-dir>/extensions/pi-provider/` 下 |
+| `PI_CODING_AGENT_DIR` | 否 | `~/.pi/agent` | 修改 Pi agent 目录 |
 
-程序化集成可以通过 `createPiProviderRuntime()` 或 `createPiProviderHost()` 配置价格回退、价格策略、请求超时、元数据 URL 和缓存路径。程序化默认值会从 `PI_CODING_AGENT_DIR`（回退到 `~/.pi/agent`）解析 agent 目录，并保持 OpenRouter 元数据缓存落盘到 `<agent-dir>/extensions/pi-provider/`，与上表一致；Pi 入口会用 Pi 自身的解析覆盖它。使用自定义 capability 根目录的 Host 包可以调用 `createPiProviderExtension({ adapterRoot, dependencies })`。源码定义 [`PiProviderDependencies`](core/runtime-config.ts) 是权威依据。
+程序化集成可以通过 `createPiProviderRuntime()` 或 `createPiProviderHost()` 配置价格策略、请求超时和 Provider 选项。程序化默认值会从 `PI_CODING_AGENT_DIR`（回退到 `~/.pi/agent`）解析 agent 目录；Pi 入口会用 Pi 自身的解析覆盖它。使用自定义 capability 根目录的 Host 包可以调用 `createPiProviderExtension({ adapterRoot, dependencies })`。源码定义 [`PiProviderDependencies`](core/runtime-config.ts) 是权威依据。
 
 ## Adapter 发现（文件级即插即用）
 
@@ -70,7 +70,7 @@ pi install npm:@hyav/pi-provider
 ```
 
 
-在目录中增删或修改文件后执行 `/reload` 即可重新发现，无需改动包；对现有文件的修改会重新从磁盘读取。用户 Adapter 在内置之后加载，因此同 ID 的用户文件会覆盖内置 Adapter（Host 保留最新注册并发出警告）。`createPiProviderExtension({ adapterRoot })` 用自定义根替换默认用户目录；内置目录始终被扫描。包内 `providers/`、`status/`、`preflight/` 下的内置 Adapter 就是采用这种写法的参考模板——复制一份改改即可（Charm Hyper 与 `preflight/openai-codex.ts` 还依赖包内私有辅助文件）。完整且不会被默认加载的 Command Code 参考实现见 [`examples/command-code`](examples/command-code/)。
+在目录中增删或修改文件后执行 `/reload` 即可重新发现，无需改动包；对现有文件的修改会重新从磁盘读取。用户 Adapter 在内置之后加载，因此同 ID 的用户文件会覆盖内置 Adapter（Host 保留最新注册并发出警告）。`createPiProviderExtension({ adapterRoot })` 用自定义根替换默认用户目录；内置目录始终被扫描。包内 `providers/`、`status/`、`preflight/` 下的内置 Adapter 就是采用这种写法的参考模板——复制一份改改即可（Charm Hyper 与 `preflight/openai-codex.ts` 还依赖包内私有辅助文件）。完整且不会被默认加载的参考实现包括 [蚂蚁数科 MaaS](examples/maas/) 和 [Command Code](examples/command-code/)。
 
 Adapter 文件从 `@hyav/pi-provider` 导入 helper 和类型（加载器内部做了别名映射）：
 
@@ -82,7 +82,7 @@ Adapter 文件不得运行时导入 Pi 的内置包（`@earendil-works/pi-coding
 
 ## 使用须知
 
-`/status` 离线运行，`/status refresh` 执行免费远程检查，`/status check` 会发送可能消耗配额的真实模型请求。配置的凭据只会发送给对应 Provider 端点，并且不会出现在 Status 输出中。
+`/status` 离线运行，`/status refresh` 执行免费远程检查并更新目录缓存，`/status check` 会发送可能消耗配额的真实模型请求。配置的凭据只会发送给对应 Provider 端点，并且不会出现在 Status 输出中。
 
 ## 许可证
 

package/core/adapter-extensions.ts

@@ -93,7 +93,14 @@ function createAdapterExtension<TAdapter extends ProviderAdapter | StatusAdapter
 			// Host runs in a different Pi module context and cannot use this
 			// extension's module-local state. The factory is retained so a Host
 			// loaded later can recreate the adapter with its configured runtime.
-			const registeredProvider = registerProviderAdapter(pi, providerAdapter, bridge.dependencies, {}, modelDrafts);
+			const piCatalog = await bridge.piCatalog;
+			const registeredProvider = registerProviderAdapter(
+				pi,
+				providerAdapter,
+				bridge.dependencies,
+				piCatalog,
+				modelDrafts,
+			);
 			emitRegistration(
 				pi,
 				{
@@ -110,7 +117,7 @@ function createAdapterExtension<TAdapter extends ProviderAdapter | StatusAdapter
 				// repeat OAuth-only replacement after binding so /reload clears a
 				// raw environment key retained by Pi's merge semantics.
 				registeredProvider.apiKey === undefined
-					? () => registerProviderAdapter(pi, providerAdapter, bridge.dependencies, {}, modelDrafts)
+					? () => registerProviderAdapter(pi, providerAdapter, bridge.dependencies, piCatalog, modelDrafts)
 					: undefined,
 			);
 			return;

package/core/adapter-protocol.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { OfficialModelMeta } from "./official-pricing.ts";
+import type { PiCatalogSnapshot } from "./pi-model-metadata.ts";
 import type { PreflightAdapter } from "./preflight-manager.ts";
 import type { PiProviderDependencies } from "./runtime-config.ts";
 import type { ProviderAdapter, ProviderModelDraft, StatusAdapter, TunerAdapter } from "./types.ts";
@@ -74,7 +74,9 @@ export type AdapterRegistrationEnvelope =
 
 export interface StartupBridge {
 	dependencies: PiProviderDependencies;
-	officialPricing: Promise<Record<string, OfficialModelMeta>>;
+	piCatalog?: Promise<PiCatalogSnapshot>;
+	/** @deprecated Generic official pricing has been removed. */
+	officialPricing?: Promise<Record<string, unknown>>;
 }
 
 export interface StartupBridgeRequest {

package/core/adapter-validation.ts

@@ -147,7 +147,9 @@ export function validateProviderAdapter(adapter: unknown): asserts adapter is Pr
 		if (
 			adapter.catalog.source !== "static" &&
 			adapter.catalog.source !== "live" &&
-			adapter.catalog.source !== "fallback"
+			adapter.catalog.source !== "cached" &&
+			adapter.catalog.source !== "fallback" &&
+			adapter.catalog.source !== "empty"
 		) {
 			throw new Error(`Provider ${adapter.id} has invalid catalog source`);
 		}
@@ -160,6 +162,17 @@ export function validateProviderAdapter(adapter: unknown): asserts adapter is Pr
 		}
 		if (adapter.catalog.updatedAt !== undefined)
 			assertFiniteNonNegative(adapter.catalog.updatedAt, "Catalog updatedAt");
+		for (const field of ["lastSuccessfulRefreshAt", "lastAttemptAt", "nextRetryAt"] as const) {
+			if (adapter.catalog[field] !== undefined) {
+				assertFiniteNonNegative(adapter.catalog[field], `Catalog ${field}`);
+			}
+		}
+		for (const field of ["consecutiveFailures", "rejectedCount", "duplicateCount"] as const) {
+			const count = adapter.catalog[field];
+			if (count !== undefined && (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0)) {
+				throw new Error(`Provider ${adapter.id} has invalid catalog ${field}`);
+			}
+		}
 		if (adapter.catalog.lastError !== undefined && !isSafeText(adapter.catalog.lastError)) {
 			throw new Error(`Provider ${adapter.id} has invalid catalog error`);
 		}

package/core/catalog-preflight.ts

@@ -1,5 +1,6 @@
 /** Shared helpers for Provider-agnostic, OpenAI-style model-catalog checks. */
 
+import { MAX_PROVIDER_MODEL_COUNT } from "./adapter-validation.ts";
 import { authDefinesHeader, getContextAuth, hasBaseUrlOrigin, mergeDiagnosticHeaders } from "./diagnostic-auth.ts";
 import { ProviderDataError } from "./errors.ts";
 import type { PreflightAdapter } from "./preflight-manager.ts";
@@ -45,6 +46,12 @@ export function createCatalogPreflightAdapter(
 		async fetch(context) {
 			const auth = await getContextAuth(context);
 			const apiKey = auth.apiKey;
+			const hasResolvedAuthHeaders = Object.values(auth.headers ?? {}).some(
+				(value) => typeof value === "string" && value !== "",
+			);
+			if (config.requireAuth !== false && !isUsableApiKey(apiKey) && !hasResolvedAuthHeaders) {
+				return { passed: false, checks: ["auth"], updatedAt: context.now() };
+			}
 			const credential = context.getCredentialType
 				? await context.getCredentialType().catch(() => undefined)
 				: undefined;
@@ -53,7 +60,7 @@ export function createCatalogPreflightAdapter(
 				"Accept-Encoding": "identity",
 				...(config.headers ?? {}),
 			});
-			if (apiKey && apiKey !== "proxy-managed") {
+			if (isUsableApiKey(apiKey)) {
 				if (config.authHeaders) {
 					for (const [name, value] of Object.entries(config.authHeaders(apiKey, credential))) {
 						if (!authDefinesHeader(auth, name)) headers.set(name, value);
@@ -90,6 +97,9 @@ export function createCatalogPreflightAdapter(
 			if (!isRecord(payload) || !Array.isArray(payload.data)) {
 				throw new ProviderDataError(`${config.name} preflight returned invalid catalog data`, "badjson");
 			}
+			if (payload.data.length > MAX_PROVIDER_MODEL_COUNT) {
+				throw new ProviderDataError(`${config.name} preflight catalog exceeds the maximum model count`, "badjson");
+			}
 			const modelIds = new Set(
 				payload.data
 					.filter(isRecord)
@@ -120,6 +130,9 @@ export function collectCatalogIds(
 	if (!isRecord(payload) || !Array.isArray(payload.data)) {
 		throw new ProviderDataError("Catalog response returned invalid catalog data", "badjson");
 	}
+	if (payload.data.length > MAX_PROVIDER_MODEL_COUNT) {
+		throw new ProviderDataError("Catalog response exceeds the maximum model count", "badjson");
+	}
 	return new Set(
 		payload.data
 			.filter(isRecord)

package/core/host.ts

@@ -17,9 +17,13 @@ import {
 	type PiProviderRuntimeController,
 	prepareProviderRegistration,
 } from "./extension.ts";
-import { fetchOfficialPricing, type OfficialModelMeta, OPENROUTER_MODELS_URL } from "./official-pricing.ts";
+import {
+	createEmptyCatalogSnapshot,
+	loadPiCatalog,
+	type PiCatalogSnapshot,
+	type PiCatalogSource,
+} from "./pi-model-metadata.ts";
 import type { PreflightAdapter } from "./preflight-manager.ts";
-import { refreshProviderRegistrations } from "./provider-registration.ts";
 import { scheduleModelCatalogRefresh } from "./runtime.ts";
 import type { PiProviderDependencies } from "./runtime-config.ts";
 import { resolvePiProviderDependencies } from "./runtime-config.ts";
@@ -45,7 +49,15 @@ function warnAdapterIssue(message: string): void {
  * event-bus envelopes are collected and assembled at the first session-level
  * operation after Pi's session_start registration barrier.
  */
-export function createPiProviderHost(dependencies: Partial<PiProviderDependencies> = {}): (pi: ExtensionAPI) => void {
+export interface PiProviderHostOptions {
+	/** Catalog functions captured from Pi's outer extension module graph. */
+	piCatalogSource?: PiCatalogSource;
+}
+
+export function createPiProviderHost(
+	dependencies: Partial<PiProviderDependencies> = {},
+	options: PiProviderHostOptions = {},
+): (pi: ExtensionAPI) => void {
 	const runtime = resolvePiProviderDependencies(dependencies);
 	return (pi) => {
 		const hostToken = {};
@@ -66,52 +78,19 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 		let readyPromise: Promise<PiProviderRuntimeController | undefined> | undefined;
 		let disposed = false;
 		let lifecycleGeneration = 0;
-		let pricingRefreshController: AbortController | undefined;
-		let latestBackgroundPricing: Record<string, OfficialModelMeta> | undefined;
-		let installedDefinition:
-			| {
-					generation: number;
-					definition: PiProviderDefinition;
-					providerDrafts: Map<ProviderAdapter, ProviderModelDraft[]>;
-			  }
-			| undefined;
-
-		const onBackgroundRefresh = (snapshot: Record<string, OfficialModelMeta>): void => {
-			latestBackgroundPricing = snapshot;
-			if (disposed || installedDefinition === undefined || installedDefinition.generation !== lifecycleGeneration)
-				return;
-			active?.updateOfficialPricing?.(snapshot);
-			// Re-register from the adapter's current registration state. A dynamic
-			// refreshModels() may have replaced the startup drafts since assembly.
-			refreshProviderRegistrations(pi, installedDefinition.definition.providers, runtime, snapshot);
-		};
-		const officialPricing = runtime.enableOfficialPricingFallback
-			? fetchOfficialPricingForHost(runtime, { allowNetwork: false })
-			: Promise.resolve({});
-		const bridge: StartupBridge = { dependencies: runtime, officialPricing };
 
-		const startOfficialPricingRefresh = (): void => {
-			pricingRefreshController?.abort();
-			pricingRefreshController = undefined;
-			if (!runtime.enableOfficialPricingFallback || disposed) {
-				return;
-			}
-			const controller = new AbortController();
-			pricingRefreshController = controller;
-			void fetchOfficialPricingForHost(runtime, { signal: controller.signal })
-				.then((snapshot) => {
-					if (controller.signal.aborted || disposed) return;
-					onBackgroundRefresh(snapshot);
-				})
-				.catch(() => undefined)
-				.finally(() => {
-					if (pricingRefreshController === controller) pricingRefreshController = undefined;
-				});
+		const piCatalogPromise = loadPiCatalog({
+			builtinCatalog: options.piCatalogSource,
+			fetch: runtime.fetch,
+		}).catch(() => createEmptyCatalogSnapshot());
+		const bridge: StartupBridge = {
+			dependencies: runtime,
+			piCatalog: piCatalogPromise,
+			officialPricing: Promise.resolve({}),
 		};
 
 		const invalidateRuntime = (): void => {
 			lifecycleGeneration++;
-			installedDefinition = undefined;
 			active?.shutdown();
 			active = undefined;
 			readyPromise = undefined;
@@ -196,7 +175,7 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 		): Promise<{
 			definition: PiProviderDefinition;
 			providerDrafts: Map<ProviderAdapter, ProviderModelDraft[]>;
-			pricing: Record<string, OfficialModelMeta>;
+			piCatalog: PiCatalogSnapshot;
 		}> => {
 			const envelopes = [...registrations.values()];
 			const providerEnvelopes = groupedWithoutConflicts(
@@ -207,7 +186,11 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 				(entry) => entry.id,
 				"provider",
 			);
-			const pricingPromise = officialPricing.catch(() => ({}));
+			const piCatalogPromise = loadPiCatalog({
+				modelRegistry: ctx?.modelRegistry,
+				builtinCatalog: options.piCatalogSource,
+				fetch: runtime.fetch,
+			}).catch(() => createEmptyCatalogSnapshot());
 			const providerResultsPromise = Promise.all(
 				providerEnvelopes.map(async (entry) => {
 					try {
@@ -220,7 +203,7 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 					}
 				}),
 			);
-			const [pricing, providerResults] = await Promise.all([pricingPromise, providerResultsPromise]);
+			const [piCatalog, providerResults] = await Promise.all([piCatalogPromise, providerResultsPromise]);
 			const providers: ProviderAdapter[] = [];
 			const providerDrafts = new Map<ProviderAdapter, ProviderModelDraft[]>();
 			for (const result of providerResults) {
@@ -236,7 +219,16 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 				try {
 					const modelDrafts =
 						result.entry.adapter.registration?.modelDrafts ?? result.entry.modelDrafts ?? adapter.provider.models;
-					prepareProviderRegistration(adapter, runtime, pricing, modelDrafts);
+					const lifecycle = adapter.lifecycle ?? (adapter.provider.refreshModels as any)?.lifecycle;
+					if (lifecycle && modelDrafts && modelDrafts.length > 0) {
+						lifecycle.setModels(
+							modelDrafts,
+							result.entry.adapter.catalog?.source,
+							result.entry.adapter.catalog?.updatedAt,
+						);
+					}
+					prepareProviderRegistration(adapter, runtime, piCatalog, modelDrafts);
+					result.entry.adapter = adapter;
 					providerDrafts.set(adapter, modelDrafts);
 					providers.push(adapter);
 				} catch (error) {
@@ -380,7 +372,7 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 				tuners: tuners.sort(compareAdapterIds),
 			};
 			validatePiProviderDefinition(definition);
-			return { definition, providerDrafts, pricing };
+			return { definition, providerDrafts, piCatalog };
 		};
 
 		const ensureReady = (ctx?: ExtensionContext): Promise<PiProviderRuntimeController | undefined> => {
@@ -389,7 +381,7 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 			const generation = lifecycleGeneration;
 			const pending = (async (): Promise<PiProviderRuntimeController | undefined> => {
 				if (disposed || generation !== lifecycleGeneration) return undefined;
-				const { definition, providerDrafts, pricing } = await buildDefinition(ctx);
+				const { definition, providerDrafts, piCatalog } = await buildDefinition(ctx);
 				if (disposed || generation !== lifecycleGeneration) return undefined;
 				const providerIds = new Set(
 					[...registrations.values()]
@@ -403,7 +395,7 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 					for (const providerId of providerIds) pi.unregisterProvider(providerId);
 				}
 				if (disposed || generation !== lifecycleGeneration) return undefined;
-				const controller = installPiProviderRuntime(pi, runtime, definition, pricing, {
+				const controller = installPiProviderRuntime(pi, runtime, definition, piCatalog, {
 					registerHandlers: false,
 					providerDrafts,
 				});
@@ -412,8 +404,6 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 					return undefined;
 				}
 				active = controller;
-				installedDefinition = { generation, definition, providerDrafts };
-				if (latestBackgroundPricing !== undefined) onBackgroundRefresh(latestBackgroundPricing);
 				return controller;
 			})();
 			readyPromise = pending.catch((error) => {
@@ -432,7 +422,6 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 		});
 		pi.on("session_start", (event, ctx) => {
 			invalidateRuntime();
-			startOfficialPricingRefresh();
 			scheduleModelCatalogRefresh(ctx, event.reason);
 		});
 		pi.on("before_provider_request", async (event, ctx) => {
@@ -447,8 +436,6 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 		});
 		pi.on("session_shutdown", () => {
 			disposed = true;
-			pricingRefreshController?.abort();
-			pricingRefreshController = undefined;
 			invalidateRuntime();
 			unsubscribeHostClaim();
 			unsubscribeBridge();
@@ -464,22 +451,3 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 		});
 	};
 }
-
-function fetchOfficialPricingForHost(
-	runtime: PiProviderDependencies,
-	options: { allowNetwork?: boolean; signal?: AbortSignal } = {},
-) {
-	return fetchOfficialPricing(
-		runtime.fetch,
-		runtime.officialPricingUrl,
-		runtime.officialPricingTimeoutMs,
-		runtime.officialPricingCacheTtlMs,
-		runtime.officialPricingMaxStaleMs,
-		runtime.now,
-		{
-			cachePath:
-				runtime.officialPricingUrl === OPENROUTER_MODELS_URL ? runtime.openRouterMetadataCachePath : undefined,
-			...options,
-		},
-	);
-}