@hyav/pi-provider 0.1.8 → 0.2.0

package/core/types.ts

@@ -4,7 +4,10 @@ import type {
 	ProviderConfig,
 	ProviderModelConfig,
 } from "@earendil-works/pi-coding-agent";
-import type { OfficialModelMeta } from "./official-pricing.ts";
+
+import type { ModelCatalogLifecycle } from "./model-catalog.ts";
+import type { PiCatalogModelMeta, PiCatalogSnapshot } from "./pi-model-metadata.ts";
+export type { PiCatalogModelMeta, PiCatalogSnapshot };
 
 export type ThinkingLevel = ReturnType<ExtensionAPI["getThinkingLevel"]>;
 
@@ -12,9 +15,17 @@ export type ProviderCost = ProviderModelConfig["cost"];
 export type ProviderModel = ProviderModelConfig;
 export type PricingSku = "input" | "output" | "cacheRead" | "cacheWrite";
 /** Pricing provenance used by Pi Provider sidecars; not added to Pi model objects. */
-export type ProviderPricingSource = "provider" | "fallback" | "official";
+export type ProviderPricingSource = "provider" | "fallback" | "official" | "pi" | "mixed";
 export type ModelPricingSource = ProviderPricingSource | "native";
-export type ModelFieldSource = ProviderPricingSource | "native" | "default" | "normalized";
+export type ModelFieldSource =
+	| "provider"
+	| "pi"
+	| "native"
+	| "default"
+	| "normalized"
+	| "mixed"
+	| "official"
+	| "fallback";
 export type ModelMetadataState = "fresh" | "stale" | "checking" | "unavailable";
 
 export interface ModelMetadataStatus {
@@ -41,8 +52,16 @@ export interface ProviderRequestAuth {
 	env?: Record<string, string>;
 }
 
+export interface ModelCostBySkuSources {
+	input?: ModelFieldSource;
+	output?: ModelFieldSource;
+	cacheRead?: ModelFieldSource;
+	cacheWrite?: ModelFieldSource;
+}
+
 export interface ModelFieldSources {
 	cost?: ModelFieldSource;
+	costBySku?: ModelCostBySkuSources;
 	contextWindow?: ModelFieldSource;
 	maxTokens?: ModelFieldSource;
 	input?: ModelFieldSource;
@@ -72,26 +91,12 @@ export interface ModelPricingDetails {
 	effectiveCost?: ProviderCost;
 	adjustment?: ProviderPricingAdjustment;
 	note?: string;
-}
-
-export interface ModelQualityScore {
-	source: string;
-	benchmark: string;
-	category: string;
-	metric: "elo" | "rating" | "score" | "ips";
-	value: number;
-	rank?: number;
-	winRate?: number;
-	confidenceInterval?: {
-		lower: number;
-		upper: number;
-	};
+	costBySku?: ModelCostBySkuSources;
 }
 
 export interface ProviderModelMetadata {
 	pricing: ModelPricingDetails;
 	fieldSources?: ModelFieldSources;
-	quality?: ModelQualityScore[];
 }
 
 export type ProviderModelDraft = Partial<ProviderModel> &
@@ -199,12 +204,16 @@ export interface ProviderAdapter {
 	/** Optional explicit price adjustments owned by this Provider. */
 	pricing?: ProviderPricingPolicy;
 	catalog?: ModelCatalogStatus;
+	lifecycle?: ModelCatalogLifecycle;
+	/** Whether to fallback to Pi's builtin catalog when fields are missing. Defaults to true. */
+	usePiModelMetaFallback?: boolean;
 	/** @internal Draft state shared across isolated Adapter and Host contexts. */
 	registration?: {
 		modelDrafts: ProviderModelDraft[];
 		normalizedModels: ProviderModel[];
 		modelMetadata: Record<string, ProviderModelMetadata>;
-		officialPricing: Record<string, OfficialModelMeta>;
+		piCatalog?: PiCatalogSnapshot;
+		officialPricing?: Record<string, any>;
 		activeRefreshes: number;
 		deferredRegistration?: () => void;
 	};

package/index.ts

@@ -1,3 +1,4 @@
+import * as piBuiltinCatalog from "@earendil-works/pi-ai/providers/all";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir, readStoredCredential } from "@earendil-works/pi-coding-agent";
 import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
@@ -17,7 +18,7 @@ export {
 	defineStatusExtension,
 	defineTunerExtension,
 } from "./core/adapter-extensions.ts";
-export { MAX_PROVIDER_MODEL_COUNT } from "./core/adapter-validation.ts";
+export { MAX_PROVIDER_MODEL_COUNT, validateProviderModelDrafts } from "./core/adapter-validation.ts";
 export { createCatalogPreflightAdapter } from "./core/catalog-preflight.ts";
 export { withDeadline } from "./core/deadline.ts";
 export {
@@ -61,26 +62,18 @@ export type {
 	ModelCatalogLifecycleOptions,
 } from "./core/model-catalog.ts";
 export { createModelCatalogLifecycle } from "./core/model-catalog.ts";
-export {
-	applyOfficialModelCosts,
-	applyOfficialModelMetadata,
-	clearPricingCache,
-	fetchOfficialModelMetadata,
-	fetchOfficialPricing,
-	findOfficialCost,
-	findOfficialMeta,
-	getDefaultOpenRouterMetadataCachePath,
-	getPricingCache,
-	getPricingCacheAge,
-	type OfficialModelMeta,
-	type OfficialModelMetadataFetchOptions,
-	type OfficialPricingFetchOptions,
-	OPENROUTER_MODELS_URL,
-	parseOpenRouterModels,
-	parseOpenRouterPricing,
-	setPricingCache,
-} from "./core/official-pricing.ts";
 export { createOpenCodeCatalogPreflightAdapter } from "./core/opencode-preflight.ts";
+export type { PiCatalogModelMeta, PiCatalogSnapshot } from "./core/pi-model-metadata.ts";
+export {
+	findPiCatalogModel,
+	isLegacyNormalizedModel,
+	isLegacyNormalizedSnapshot,
+	loadPiCatalog,
+	mergeModelWithPiCatalog,
+	ORIGINAL_PI_PROVIDER_ALLOWLIST,
+	parsePiCatalogFromProviders,
+	toPiCatalogSnapshot,
+} from "./core/pi-model-metadata.ts";
 export type {
 	PreflightAdapter,
 	PreflightContext,
@@ -97,18 +90,23 @@ export type { RateLimitWindow } from "./core/ratelimit-headers.ts";
 export { parseRetryAfter } from "./core/retry-after.ts";
 export type { StatusDiagnostics, StatusErrorState } from "./core/status-manager.ts";
 export { normalizeStatusSnapshot, StatusManager } from "./core/status-manager.ts";
+export {
+	formatProviderStatus,
+	getStatusModeCompletions,
+	parseStatusMode,
+} from "./core/status-report.ts";
 export { applyTunerAdapters, sortTunerAdapters } from "./core/tuner-manager.ts";
 export type {
 	ActiveModel,
 	ModelCatalogSource,
 	ModelCatalogStatus,
+	ModelCostBySkuSources,
 	ModelFieldSource,
 	ModelFieldSources,
 	ModelMetadataState,
 	ModelMetadataStatus,
 	ModelPricingDetails,
 	ModelPricingSource,
-	ModelQualityScore,
 	PiApi,
 	PricingSku,
 	ProviderAdapter,
@@ -156,6 +154,11 @@ export function createPiProviderExtension(
 					wrapTextWithAnsi: typeof wrapTextWithAnsi;
 					adapterRoot?: string;
 					dependencies?: Partial<PiProviderDependencies>;
+					piCatalogSource: {
+						getBuiltinProviders: () => string[];
+						getBuiltinModels: (provider: string) => unknown[];
+						getBuiltinModelDataGeneratedAt: () => number | undefined;
+					};
 				},
 			) => Promise<void>;
 		};
@@ -165,6 +168,12 @@ export function createPiProviderExtension(
 			wrapTextWithAnsi,
 			adapterRoot: options.adapterRoot,
 			dependencies: options.dependencies,
+			piCatalogSource: {
+				getBuiltinProviders: () => piBuiltinCatalog.getBuiltinProviders(),
+				getBuiltinModels: (provider) =>
+					piBuiltinCatalog.getBuiltinModels(provider as Parameters<typeof piBuiltinCatalog.getBuiltinModels>[0]),
+				getBuiltinModelDataGeneratedAt: () => piBuiltinCatalog.getBuiltinModelDataGeneratedAt?.(),
+			},
 		});
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyav/pi-provider",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Provider extension toolkit for Pi to integrate and manage custom LLM providers with dynamic models, request tuners, and account status.",
   "author": "hyav",
   "license": "MIT",
@@ -44,11 +44,13 @@
     "node": ">=22.19.0"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.5",
+    "@earendil-works/pi-ai": "0.84.1",
     "@earendil-works/pi-coding-agent": "0.84.1",
     "@earendil-works/pi-tui": "0.84.1",
     "@types/node": "22.20.1",

package/preflight/charm-hyper.ts

@@ -13,9 +13,13 @@ export function createCharmHyperPreflightAdapter(requestTimeoutMs: number): Pref
 		supportsModel: (model) => hasBaseUrlOrigin(model.baseUrl, HYPER_PROVIDER_URL),
 		async fetch(context) {
 			const apiKey = await context.getApiKey();
-			if (!apiKey) return { passed: false, checks: ["auth"], updatedAt: context.now() };
+			// "proxy-managed" is not a usable credential for the official endpoints,
+			// so it fails closed together with a missing key.
+			if (!apiKey || apiKey === "proxy-managed") {
+				return { passed: false, checks: ["auth"], updatedAt: context.now() };
+			}
 			const headers = new Headers(hyperJsonHeaders());
-			if (apiKey !== "proxy-managed") headers.set("Authorization", `Bearer ${apiKey}`);
+			headers.set("Authorization", `Bearer ${apiKey}`);
 			let endpoint = HYPER_PROVIDER_URL;
 			let response = await context.fetch(endpoint, { headers, signal: context.signal });
 			if (response.status === 404) {

package/preflight/deepseek.ts

@@ -1,5 +1,11 @@
 import type { PreflightAdapter } from "@hyav/pi-provider";
-import { definePreflightExtension, hasBaseUrlOrigin, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
+import {
+	definePreflightExtension,
+	hasBaseUrlOrigin,
+	MAX_PROVIDER_MODEL_COUNT,
+	ProviderDataError,
+	parseRetryAfter,
+} from "@hyav/pi-provider";
 
 export const DEEPSEEK_MODELS_URL = "https://api.deepseek.com/models";
 
@@ -44,6 +50,9 @@ export const deepSeekPreflightAdapter: PreflightAdapter = {
 		if (!isRecord(payload) || !Array.isArray(payload.data)) {
 			throw new ProviderDataError("DeepSeek preflight returned invalid catalog data", "badjson");
 		}
+		if (payload.data.length > MAX_PROVIDER_MODEL_COUNT) {
+			throw new ProviderDataError("DeepSeek preflight catalog exceeds the maximum model count", "badjson");
+		}
 		const modelIds = new Set(
 			payload.data
 				.filter(isRecord)

package/preflight/github-copilot.ts

@@ -4,6 +4,7 @@ import {
 	authDefinesHeader,
 	definePreflightExtension,
 	getContextAuth,
+	MAX_PROVIDER_MODEL_COUNT,
 	mergeDiagnosticHeaders,
 	ProviderDataError,
 	parseRetryAfter,
@@ -57,6 +58,9 @@ export const githubCopilotPreflightAdapter: PreflightAdapter = {
 		if (!isRecord(payload) || !Array.isArray(payload.data)) {
 			throw new ProviderDataError("GitHub Copilot preflight returned invalid catalog data", "badjson");
 		}
+		if (payload.data.length > MAX_PROVIDER_MODEL_COUNT) {
+			throw new ProviderDataError("GitHub Copilot preflight catalog exceeds the maximum model count", "badjson");
+		}
 		const modelIds = new Set(
 			payload.data.flatMap((model) => {
 				if (!isRecord(model) || typeof model.id !== "string") return [];

package/preflight/google.ts

@@ -1,5 +1,11 @@
 import type { PreflightAdapter } from "@hyav/pi-provider";
-import { definePreflightExtension, hasBaseUrlOrigin, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
+import {
+	definePreflightExtension,
+	hasBaseUrlOrigin,
+	MAX_PROVIDER_MODEL_COUNT,
+	ProviderDataError,
+	parseRetryAfter,
+} from "@hyav/pi-provider";
 
 export const GOOGLE_MODELS_URL = "https://generativelanguage.googleapis.com/v1beta/models";
 
@@ -59,6 +65,9 @@ export const googlePreflightAdapter: PreflightAdapter = {
 		if (!isRecord(payload) || !Array.isArray(payload.models)) {
 			throw new ProviderDataError("Google preflight returned invalid catalog data", "badjson");
 		}
+		if (payload.models.length > MAX_PROVIDER_MODEL_COUNT) {
+			throw new ProviderDataError("Google preflight catalog exceeds the maximum model count", "badjson");
+		}
 		const modelIds = new Set(
 			payload.models.flatMap((value) => {
 				if (!isRecord(value)) return [];

package/preflight/groq.ts

@@ -1,5 +1,11 @@
 import type { PreflightAdapter } from "@hyav/pi-provider";
-import { definePreflightExtension, hasBaseUrlOrigin, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
+import {
+	definePreflightExtension,
+	hasBaseUrlOrigin,
+	MAX_PROVIDER_MODEL_COUNT,
+	ProviderDataError,
+	parseRetryAfter,
+} from "@hyav/pi-provider";
 import { GROQ_MODELS_URL } from "../status/groq.ts";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -43,6 +49,9 @@ export const groqPreflightAdapter: PreflightAdapter = {
 		if (!isRecord(payload) || !Array.isArray(payload.data)) {
 			throw new ProviderDataError("Groq preflight returned invalid catalog data", "badjson");
 		}
+		if (payload.data.length > MAX_PROVIDER_MODEL_COUNT) {
+			throw new ProviderDataError("Groq preflight catalog exceeds the maximum model count", "badjson");
+		}
 		const activeIds = new Set(
 			payload.data.flatMap((model) => {
 				if (!isRecord(model) || typeof model.id !== "string") return [];

package/preflight/openai-codex.ts

@@ -1,5 +1,11 @@
 import type { PreflightAdapter } from "@hyav/pi-provider";
-import { definePreflightExtension, hasBaseUrlOrigin, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
+import {
+	definePreflightExtension,
+	hasBaseUrlOrigin,
+	MAX_PROVIDER_MODEL_COUNT,
+	ProviderDataError,
+	parseRetryAfter,
+} from "@hyav/pi-provider";
 import { extractCodexAccountId } from "../status/openai-codex.ts";
 
 export const CODEX_MODELS_URL = "https://chatgpt.com/backend-api/codex/models";
@@ -13,6 +19,9 @@ function codexModelIds(payload: unknown): Set<string> {
 	if (!isRecord(payload) || !Array.isArray(payload.models)) {
 		throw new ProviderDataError("OpenAI Codex preflight returned invalid catalog data", "badjson");
 	}
+	if (payload.models.length > MAX_PROVIDER_MODEL_COUNT) {
+		throw new ProviderDataError("OpenAI Codex preflight catalog exceeds the maximum model count", "badjson");
+	}
 	return new Set(
 		payload.models
 			.filter(isRecord)

package/preflight/openrouter.ts

@@ -1,5 +1,11 @@
 import type { PreflightAdapter } from "@hyav/pi-provider";
-import { definePreflightExtension, hasBaseUrlOrigin, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
+import {
+	definePreflightExtension,
+	hasBaseUrlOrigin,
+	MAX_PROVIDER_MODEL_COUNT,
+	ProviderDataError,
+	parseRetryAfter,
+} from "@hyav/pi-provider";
 import { OPENROUTER_KEY_URL } from "../status/openrouter.ts";
 
 export const OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models";
@@ -34,6 +40,9 @@ async function collectModelIds(context: Parameters<PreflightAdapter["fetch"]>[0]
 	if (!isRecord(payload) || !Array.isArray(payload.data)) {
 		throw new ProviderDataError("OpenRouter preflight returned invalid catalog data", "badjson");
 	}
+	if (payload.data.length > MAX_PROVIDER_MODEL_COUNT) {
+		throw new ProviderDataError("OpenRouter preflight catalog exceeds the maximum model count", "badjson");
+	}
 	return new Set(
 		payload.data
 			.filter(isRecord)
@@ -85,7 +94,7 @@ export const openRouterPreflightAdapter: PreflightAdapter = {
 		const apiKey = await context.getApiKey();
 		const checks: string[] = ["endpoint", "catalog"];
 		if (!apiKey || apiKey === "proxy-managed") {
-			return { passed: modelIds.has(context.model.id), checks: [...checks, "auth"], updatedAt: context.now() };
+			return { passed: false, checks: [...checks, "auth"], updatedAt: context.now() };
 		}
 		// Management keys use /api/v1/credits as the only key endpoint and get 404 here.
 		const authStatus = await checkCredential(context, apiKey);

package/preflight/vercel-ai-gateway.ts

@@ -1,5 +1,10 @@
 import type { PreflightAdapter, PreflightSnapshot } from "@hyav/pi-provider";
-import { definePreflightExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
+import {
+	definePreflightExtension,
+	MAX_PROVIDER_MODEL_COUNT,
+	ProviderDataError,
+	parseRetryAfter,
+} from "@hyav/pi-provider";
 import { VERCEL_PROVIDER_ID } from "../status/vercel-ai-gateway/constants.ts";
 
 export const VERCEL_MODELS_URL = "https://ai-gateway.vercel.sh/v1/models";
@@ -12,6 +17,9 @@ export function parseVercelModelIds(payload: unknown): Set<string> {
 	if (!isRecord(payload) || !Array.isArray(payload.data)) {
 		throw new ProviderDataError("Vercel AI Gateway preflight returned invalid catalog data", "badjson");
 	}
+	if (payload.data.length > MAX_PROVIDER_MODEL_COUNT) {
+		throw new ProviderDataError("Vercel AI Gateway preflight catalog exceeds the maximum model count", "badjson");
+	}
 
 	const modelIds = new Set<string>();
 	for (const value of payload.data) {
@@ -37,6 +45,8 @@ export function createVercelAIGatewayPreflightAdapter(requestTimeoutMs: number):
 		cacheTtlMs: 30_000,
 		requestTimeoutMs,
 		async fetch(context): Promise<PreflightSnapshot> {
+			// Vercel's gateway catalog is public and needs no credential; the
+			// check intentionally reports no "auth" check.
 			const response = await context.fetch(VERCEL_MODELS_URL, {
 				headers: {
 					Accept: "application/json",

package/preflight/xai.ts

@@ -1,5 +1,11 @@
 import type { PreflightAdapter } from "@hyav/pi-provider";
-import { definePreflightExtension, hasBaseUrlOrigin, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
+import {
+	definePreflightExtension,
+	hasBaseUrlOrigin,
+	MAX_PROVIDER_MODEL_COUNT,
+	ProviderDataError,
+	parseRetryAfter,
+} from "@hyav/pi-provider";
 import { XAI_MODELS_URL } from "../status/xai.ts";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -15,12 +21,18 @@ export const xaiPreflightAdapter: PreflightAdapter = {
 	supportsModel: (model) => hasBaseUrlOrigin(model.baseUrl, XAI_MODELS_URL),
 	async fetch(context) {
 		const apiKey = await context.getApiKey();
+		if (!apiKey || apiKey === "proxy-managed") {
+			// xAI authenticates every route, including /v1/models, so without a
+			// credential the catalog request cannot succeed. Fail closed instead
+			// of reporting a catalog match as a usable model.
+			return { passed: false, checks: ["auth"], updatedAt: context.now() };
+		}
 		const authHeaders: Record<string, string> = {
 			Accept: "application/json",
 			"Accept-Encoding": "identity",
 			"User-Agent": "@hyav/pi-provider",
+			Authorization: `Bearer ${apiKey}`,
 		};
-		if (apiKey && apiKey !== "proxy-managed") authHeaders.Authorization = `Bearer ${apiKey}`;
 		const response = await context.fetch(XAI_MODELS_URL, {
 			headers: authHeaders,
 			signal: context.signal,
@@ -42,16 +54,18 @@ export const xaiPreflightAdapter: PreflightAdapter = {
 		if (!isRecord(payload) || !Array.isArray(payload.data)) {
 			throw new ProviderDataError("xAI preflight returned invalid catalog data", "badjson");
 		}
+		if (payload.data.length > MAX_PROVIDER_MODEL_COUNT) {
+			throw new ProviderDataError("xAI preflight catalog exceeds the maximum model count", "badjson");
+		}
 		const modelIds = new Set(
 			payload.data
 				.filter(isRecord)
 				.map((model) => (typeof model.id === "string" ? model.id.trim() : undefined))
 				.filter((id): id is string => id !== undefined && id !== ""),
 		);
-		const checks = apiKey && apiKey !== "proxy-managed" ? ["endpoint", "catalog", "auth"] : ["endpoint", "catalog"];
 		return {
 			passed: modelIds.has(context.model.id),
-			checks,
+			checks: ["endpoint", "catalog", "auth"],
 			updatedAt: context.now(),
 			httpStatus: response.status,
 		};

package/providers/charm-hyper/oauth.ts

@@ -156,21 +156,20 @@ function parseDevicePollResponse(payload: unknown): DevicePollResult {
 }
 
 function parseTokenExchangeResponse(payload: unknown): TokenExchangeResponse {
+	const allowedKeys = ["access_token", "token_type", "refresh_token", "expiry", "expires_in", "expires_at"] as const;
 	if (
 		!isRecord(payload) ||
+		!hasOnlyKeys(payload, allowedKeys) ||
 		!nonEmptyString(payload.access_token) ||
 		!nonEmptyString(payload.token_type) ||
 		!nonEmptyString(payload.refresh_token) ||
-		!nonEmptyString(payload.expiry)
+		typeof payload.expiry !== "string"
 	) {
 		throw new Error("Charm Hyper token exchange response is invalid");
 	}
 	if (Object.hasOwn(payload, "expires_in")) {
-		if (
-			!hasOnlyKeys(payload, ["access_token", "token_type", "refresh_token", "expiry", "expires_in"]) ||
-			!positiveInteger(payload.expires_in) ||
-			Object.hasOwn(payload, "expires_at")
-		) {
+		// expires_in is authoritative when other absolute forms are also present.
+		if (!positiveInteger(payload.expires_in)) {
 			throw new Error("Charm Hyper token exchange response has an invalid expiry");
 		}
 		return {
@@ -180,10 +179,7 @@ function parseTokenExchangeResponse(payload: unknown): TokenExchangeResponse {
 		};
 	}
 	if (Object.hasOwn(payload, "expires_at")) {
-		if (
-			!hasOnlyKeys(payload, ["access_token", "token_type", "refresh_token", "expiry", "expires_at"]) ||
-			!positiveInteger(payload.expires_at)
-		) {
+		if (!positiveInteger(payload.expires_at)) {
 			throw new Error("Charm Hyper token exchange response has an invalid expiry");
 		}
 		return {
@@ -192,7 +188,17 @@ function parseTokenExchangeResponse(payload: unknown): TokenExchangeResponse {
 			expiresAtSeconds: payload.expires_at,
 		};
 	}
-	throw new Error("Charm Hyper token exchange response has an invalid expiry");
+	// Some responses only carry the ISO `expiry` timestamp; derive the
+	// absolute expiry from it when no numeric form is present.
+	const expiryMs = typeof payload.expiry === "string" ? Date.parse(payload.expiry) : NaN;
+	if (!Number.isFinite(expiryMs)) {
+		throw new Error("Charm Hyper token exchange response has an invalid expiry");
+	}
+	return {
+		accessToken: payload.access_token,
+		refreshToken: payload.refresh_token,
+		expiresAtSeconds: Math.floor(expiryMs / 1_000),
+	};
 }
 
 async function initiateDeviceAuth(

package/providers/charm-hyper.ts

@@ -9,10 +9,11 @@ import type {
 import {
 	createModelCatalogLifecycle,
 	defineProviderExtension,
+	isLegacyNormalizedSnapshot,
 	isProviderDataError,
 	MAX_PROVIDER_MODEL_COUNT,
-	normalizeProviderModels,
 	ProviderDataError,
+	validateProviderModelDrafts,
 	withDeadline,
 } from "@hyav/pi-provider";
 import { HYPER_BASE_URL, HYPER_USER_AGENT, hyperJsonHeaders } from "./charm-hyper/constants.ts";
@@ -98,7 +99,8 @@ function parseCurrentHyperModel(value: unknown): ProviderModelDraft | undefined
 	if (typeof value.name !== "string" || value.name.trim() === "") return undefined;
 	if (!isFiniteNonNegative(value.cost_per_1m_in)) return undefined;
 	if (!isFiniteNonNegative(value.cost_per_1m_out)) return undefined;
-	if (!isFiniteNonNegative(value.cost_per_1m_in_cached)) return undefined;
+	// Cached prices are optional; the manifest documents 0/missing as no discount.
+	if (value.cost_per_1m_in_cached !== undefined && !isFiniteNonNegative(value.cost_per_1m_in_cached)) return undefined;
 	if (value.cost_per_1m_out_cached !== undefined && !isFiniteNonNegative(value.cost_per_1m_out_cached))
 		return undefined;
 	if (!isPositiveInteger(value.context_window) || !isPositiveInteger(value.default_max_tokens)) return undefined;
@@ -137,8 +139,10 @@ function parseCurrentHyperModel(value: unknown): ProviderModelDraft | undefined
 		cost: {
 			input: value.cost_per_1m_in,
 			output: value.cost_per_1m_out,
-			cacheRead: value.cost_per_1m_in_cached,
-			cacheWrite: 0,
+			// Official Charm mapping: the cached-output price is the cache-read
+			// price and the cached-input price is the cache-write price.
+			cacheRead: value.cost_per_1m_out_cached ?? 0,
+			cacheWrite: value.cost_per_1m_in_cached ?? 0,
 		},
 		contextWindow: value.context_window,
 		maxTokens: value.default_max_tokens,
@@ -308,7 +312,7 @@ async function discoverHyperModels(
 			if (parsed.models.length === 0) {
 				throw new ProviderDataError("Charm Hyper model discovery returned no valid models", "badjson");
 			}
-			normalizeProviderModels(parsed.models);
+			validateProviderModelDrafts(parsed.models);
 			return parsed;
 		},
 		timeoutMs,
@@ -330,15 +334,18 @@ function catalogErrorCode(error: unknown): string {
 }
 
 type HyperModelsStoreEntry = ProviderRefreshContext["stored"];
-type HyperStoredModel = NonNullable<HyperModelsStoreEntry>["models"][number] & {
-	pricingSource?: ProviderModelDraft["pricingSource"];
+type HyperStoredModel = ProviderModelDraft & {
+	provider: string;
+	baseUrl: string;
+	api: ProviderModelDraft["api"];
 };
 
 function draftsFromStoredModels(entry: HyperModelsStoreEntry): ProviderModelDraft[] | undefined {
 	if (!entry || !Array.isArray(entry.models) || entry.models.length === 0) return undefined;
+	if (isLegacyNormalizedSnapshot(entry.models)) return undefined;
 	try {
 		const drafts: ProviderModelDraft[] = entry.models.map(({ provider: _provider, ...model }) => model);
-		normalizeProviderModels(drafts);
+		validateProviderModelDrafts(drafts);
 		return drafts;
 	} catch {
 		return undefined;
@@ -346,10 +353,12 @@ function draftsFromStoredModels(entry: HyperModelsStoreEntry): ProviderModelDraf
 }
 
 function storedModelsFromDrafts(models: ProviderModelDraft[]): HyperStoredModel[] {
-	return normalizeProviderModels(models).map((model) => {
-		const source = models.find(({ id }) => id === model.id)?.pricingSource;
+	validateProviderModelDrafts(models);
+	return models.map((model) => {
+		const source = model.pricingSource;
 		return {
 			...model,
+			name: typeof model.name === "string" && model.name.trim() !== "" ? model.name.trim() : model.id,
 			...(source ? { pricingSource: source } : {}),
 			api: model.api ?? "openai-completions",
 			provider: "charm-hyper",
@@ -362,14 +371,19 @@ export function createCharmHyperAdapter(
 	fetchFn: typeof globalThis.fetch,
 	discoveryTimeoutMs: number,
 	now: () => number = Date.now,
+	initialModels?: ProviderModelDraft[],
 ): ProviderAdapter {
 	let provider: ProviderAdapter["provider"];
 	const lifecycle = createModelCatalogLifecycle({
+		initialModels,
 		ttlMs: HYPER_MODEL_CATALOG_TTL_MS,
 		now,
 		discover: (context) => discoverHyperModels(fetchFn, discoveryTimeoutMs, context.signal),
 		restore: draftsFromStoredModels,
-		persist: (models, checkedAt) => ({ models: storedModelsFromDrafts(models), checkedAt }),
+		persist: (models, checkedAt) => ({
+			models: storedModelsFromDrafts(models) as unknown as NonNullable<HyperModelsStoreEntry>["models"],
+			checkedAt,
+		}),
 		onUpdate: (models) => {
 			if (provider) provider.models = models;
 		},
@@ -387,7 +401,7 @@ export function createCharmHyperAdapter(
 		oauth: createCharmHyperOAuth(fetchFn, now),
 	};
 
-	return { id: "charm-hyper", catalog: lifecycle.catalog, provider };
+	return { id: "charm-hyper", catalog: lifecycle.catalog, lifecycle, provider };
 }
 
 const charmHyperProviderExtension = defineProviderExtension({

package/status/huggingface.ts

@@ -31,10 +31,11 @@ export function parseHuggingFaceAccount(payload: unknown): HuggingFaceAccount {
 	}
 	// Response envelope: { type, id, name, emailVerified, canPay, isPro, plan, periodEnd, credits, ... }
 	const plan = safeText(payload.plan);
+	const credits = finiteNumber(payload.credits);
 	// Older token generations omit the envelope fields entirely.
 	return {
 		...(plan !== undefined ? { plan } : {}),
-		...(finiteNumber(payload.credits) !== undefined ? { credits: finiteNumber(payload.credits) } : {}),
+		...(credits !== undefined ? { credits } : {}),
 	};
 }
 

package/status/openrouter.ts

@@ -149,8 +149,14 @@ export const openRouterStatusAdapter: StatusAdapter = {
 				unit: "USD",
 			};
 		} catch (error) {
-			// Safe fallback: key credits, free-tier, and key-level limit still display.
-			if (!(error instanceof ProviderDataError)) throw error;
+			// /credits requires a management key, so permission-shaped failures
+			// degrade to the key payload; real failures must still surface.
+			if (
+				!(error instanceof ProviderDataError) ||
+				(error.httpStatus !== 401 && error.httpStatus !== 403 && error.httpStatus !== 404)
+			) {
+				throw error;
+			}
 		}
 
 		return {