@hyav/pi-provider 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 This file is the authoritative user-facing release history for `@hyav/pi-provider`.
 
+## 0.1.5 - 2026-08-24
+
+- Skip network model-catalog refreshes for Providers whose environment-backed API key is not configured and which have no resolved stored credential, retaining cached models without Pi refresh warnings.
+- Apply bounded validation to initial, cached, and refreshed model catalogs, including model-count, field-length, and control-character checks.
+- Route Status, Preflight, and Live Check requests through each model credential's effective headers and base URL, and skip account endpoints that cannot be mapped without risking credential disclosure.
+- Defer official metadata network refreshes until session startup, cancel them during shutdown, and preserve refreshed dynamic catalogs when pricing updates race with model discovery.
+- Derive metadata cache paths after resolving the agent directory and disable persistence when no agent directory is configured.
+- Report the Vercel AI Gateway public catalog check without claiming it verifies authentication.
+- Export diagnostic authentication helpers through the public Adapter API so installed user Adapters remain independently loadable.
+
 ## 0.1.4 - 2026-08-21
 
 - Add Status and Preflight Adapters for the Vercel AI Gateway (auth, model catalog, and credits).

package/README.md

@@ -45,6 +45,8 @@ 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.
+
 ## Common configuration
 
 | Name | Required | Default | Effect |
@@ -68,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).
+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/).
 
 Adapter files import helpers and types from `@hyav/pi-provider` (aliased inside the loader):
 

package/README.zh-CN.md

@@ -45,6 +45,8 @@ pi install npm:@hyav/pi-provider
 
 使用 `/status refresh` 执行免费的端点、鉴权、目录和账户检查。只有明确接受一次真实模型请求及其可能产生的用量费用时，才使用 `/status check`。
 
+动态 Provider 的 API Key 引用环境变量时，如果这些变量和已存储凭据均未配置，将保留缓存或回退模型目录并跳过网络刷新，避免未配置的 Provider 产生模型目录刷新警告。
+
 ## 常用配置
 
 | 名称 | 必需 | 默认值 | 作用 |
@@ -68,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` 还依赖包内私有辅助文件）。
+在目录中增删或修改文件后执行 `/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/)。
 
 Adapter 文件从 `@hyav/pi-provider` 导入 helper 和类型（加载器内部做了别名映射）：
 

package/core/adapter-validation.ts

@@ -1,13 +1,15 @@
 import { isValidTimeoutMs } from "./deadline.ts";
 import type { PreflightAdapter } from "./preflight-manager.ts";
 import { validatePricingAdjustment, validatePricingPolicy } from "./pricing-adjustments.ts";
-import type { ProviderAdapter, StatusAdapter, TunerAdapter } from "./types.ts";
+import type { ProviderAdapter, ProviderModelDraft, StatusAdapter, TunerAdapter } from "./types.ts";
 
 export type AdapterValue = ProviderAdapter | StatusAdapter | PreflightAdapter | TunerAdapter;
 
 const MAX_STABLE_ID_LENGTH = 128;
 const MAX_TEXT_LENGTH = 1_024;
 const MAX_MODEL_ID_LENGTH = 512;
+/** Maximum accepted models in one initial, cached, or refreshed Provider catalog. */
+export const MAX_PROVIDER_MODEL_COUNT = 4_096;
 
 export function isStableAdapterId(value: unknown): value is string {
 	return (
@@ -16,7 +18,7 @@ export function isStableAdapterId(value: unknown): value is string {
 		value.length <= MAX_STABLE_ID_LENGTH &&
 		value.trim() === value &&
 		!/\s/.test(value) &&
-		!/[\u0000-\u001f\u007f]/.test(value)
+		!/[\u0000-\u001f\u007f-\u009f]/.test(value)
 	);
 }
 
@@ -29,7 +31,7 @@ function isSafeText(value: unknown, maxLength = MAX_TEXT_LENGTH): value is strin
 		typeof value === "string" &&
 		value.trim() !== "" &&
 		value.length <= maxLength &&
-		!/[\u0000-\u001f\u007f]/.test(value)
+		!/[\u0000-\u001f\u007f-\u009f]/.test(value)
 	);
 }
 
@@ -95,6 +97,17 @@ function validateProviderModelDraft(value: unknown, label: string): void {
 	if (value.thinkingLevelMap !== undefined) assertAdapterObject(value.thinkingLevelMap, `${label}.thinkingLevelMap`);
 }
 
+export function validateProviderModelDrafts(
+	value: unknown,
+	label = "Provider model catalog",
+): asserts value is ProviderModelDraft[] {
+	if (!Array.isArray(value)) throw new Error(`${label} must be an array`);
+	if (value.length > MAX_PROVIDER_MODEL_COUNT) {
+		throw new Error(`${label} has too many models (maximum ${MAX_PROVIDER_MODEL_COUNT})`);
+	}
+	for (const [index, model] of value.entries()) validateProviderModelDraft(model, `${label} model ${index}`);
+}
+
 export function validateProviderAdapter(adapter: unknown): asserts adapter is ProviderAdapter {
 	assertAdapterObject(adapter, "Provider adapter");
 	assertStableId(adapter.id, "Provider adapter ID");
@@ -125,9 +138,7 @@ export function validateProviderAdapter(adapter: unknown): asserts adapter is Pr
 		}
 	}
 	if (!Array.isArray(provider.models)) throw new Error(`Provider ${adapter.id} must define a model list`);
-	for (const [index, model] of provider.models.entries()) {
-		validateProviderModelDraft(model, `Provider ${adapter.id} model ${index}`);
-	}
+	validateProviderModelDrafts(provider.models, `Provider ${adapter.id}`);
 	if (provider.refreshModels !== undefined && typeof provider.refreshModels !== "function") {
 		throw new Error(`Provider ${adapter.id} has invalid refreshModels`);
 	}
@@ -165,6 +176,9 @@ export function validateStatusAdapter(adapter: unknown): asserts adapter is Stat
 		throw new Error(`Status ${adapter.id} has invalid cache TTL`);
 	}
 	if (!isValidTimeoutMs(adapter.requestTimeoutMs)) throw new Error(`Status ${adapter.id} has invalid timing settings`);
+	if (adapter.supportsModel !== undefined && typeof adapter.supportsModel !== "function") {
+		throw new Error(`Status ${adapter.id} has invalid model support policy`);
+	}
 }
 
 export function validatePreflightAdapter(adapter: unknown): asserts adapter is PreflightAdapter {
@@ -179,6 +193,9 @@ export function validatePreflightAdapter(adapter: unknown): asserts adapter is P
 	if (!isValidTimeoutMs(adapter.requestTimeoutMs)) {
 		throw new Error(`Preflight ${adapter.id} has invalid timing settings`);
 	}
+	if (adapter.supportsModel !== undefined && typeof adapter.supportsModel !== "function") {
+		throw new Error(`Preflight ${adapter.id} has invalid model support policy`);
+	}
 }
 
 export function validateTunerAdapter(adapter: unknown): asserts adapter is TunerAdapter {

package/core/catalog-preflight.ts

@@ -1,5 +1,6 @@
 /** Shared helpers for Provider-agnostic, OpenAI-style model-catalog checks. */
 
+import { authDefinesHeader, getContextAuth, hasBaseUrlOrigin, mergeDiagnosticHeaders } from "./diagnostic-auth.ts";
 import { ProviderDataError } from "./errors.ts";
 import type { PreflightAdapter } from "./preflight-manager.ts";
 import { parseRetryAfter } from "./retry-after.ts";
@@ -42,25 +43,36 @@ export function createCatalogPreflightAdapter(
 		cacheTtlMs: 30_000,
 		requestTimeoutMs,
 		async fetch(context) {
-			const apiKey = await context.getApiKey();
+			const auth = await getContextAuth(context);
+			const apiKey = auth.apiKey;
 			const credential = context.getCredentialType
 				? await context.getCredentialType().catch(() => undefined)
 				: undefined;
-			const headers: Record<string, string> = {
+			const headers = mergeDiagnosticHeaders(auth, {
 				Accept: "application/json",
 				"Accept-Encoding": "identity",
 				...(config.headers ?? {}),
-			};
+			});
 			if (apiKey && apiKey !== "proxy-managed") {
 				if (config.authHeaders) {
-					Object.assign(headers, config.authHeaders(apiKey, credential));
+					for (const [name, value] of Object.entries(config.authHeaders(apiKey, credential))) {
+						if (!authDefinesHeader(auth, name)) headers.set(name, value);
+					}
 				} else if (config.keyHeader) {
-					headers[config.keyHeader] = apiKey;
-				} else {
-					headers.Authorization = `Bearer ${apiKey}`;
+					if (!authDefinesHeader(auth, config.keyHeader)) headers.set(config.keyHeader, apiKey);
+				} else if (!authDefinesHeader(auth, "Authorization")) {
+					headers.set("Authorization", `Bearer ${apiKey}`);
 				}
 			}
-			const response = await context.fetch(config.modelsUrl, { headers, signal: context.signal });
+			const effectiveBaseUrl = context.model.baseUrl ?? auth.baseUrl;
+			const modelsUrl =
+				effectiveBaseUrl === undefined || hasBaseUrlOrigin(effectiveBaseUrl, config.modelsUrl)
+					? config.modelsUrl
+					: workspaceModelsUrl(effectiveBaseUrl);
+			if (!modelsUrl) {
+				throw new ProviderDataError(`${config.name} model catalog is unavailable for this endpoint`, "unsupported");
+			}
+			const response = await context.fetch(modelsUrl, { headers, signal: context.signal });
 			if (!response.ok) {
 				throw new ProviderDataError(
 					`${config.name} preflight failed: HTTP ${response.status}`,

package/core/diagnostic-auth.ts

@@ -0,0 +1,103 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ProviderDataError } from "./errors.ts";
+import type { ProviderRequestAuth } from "./types.ts";
+
+type DiagnosticModel = NonNullable<ExtensionContext["model"]>;
+type ModelRegistry = ExtensionContext["modelRegistry"];
+
+export interface DiagnosticModelRegistry {
+	getApiKeyAndHeaders?: ModelRegistry["getApiKeyAndHeaders"];
+	getApiKeyForProvider?: ModelRegistry["getApiKeyForProvider"];
+}
+
+export async function resolveDiagnosticAuth(
+	model: DiagnosticModel,
+	modelRegistry: DiagnosticModelRegistry,
+): Promise<ProviderRequestAuth> {
+	if (typeof modelRegistry.getApiKeyAndHeaders === "function") {
+		const resolved = await modelRegistry.getApiKeyAndHeaders(model);
+		if (!resolved.ok) throw new ProviderDataError(resolved.error, "auth");
+		return {
+			...(resolved.apiKey !== undefined ? { apiKey: resolved.apiKey } : {}),
+			...(resolved.headers !== undefined ? { headers: { ...resolved.headers } } : {}),
+			baseUrl: resolved.baseUrl ?? model.baseUrl,
+			...(resolved.env !== undefined ? { env: { ...resolved.env } } : {}),
+		};
+	}
+
+	const apiKey =
+		typeof modelRegistry.getApiKeyForProvider === "function"
+			? await modelRegistry.getApiKeyForProvider(model.provider)
+			: undefined;
+	return {
+		...(apiKey !== undefined ? { apiKey } : {}),
+		baseUrl: model.baseUrl,
+	};
+}
+
+export function applyDiagnosticBaseUrl<T extends DiagnosticModel>(model: T, auth: ProviderRequestAuth): T {
+	return auth.baseUrl !== undefined && auth.baseUrl !== model.baseUrl ? { ...model, baseUrl: auth.baseUrl } : model;
+}
+
+/** Read full diagnostic auth, falling back to the legacy API-key accessor for direct adapter use. */
+export async function getContextAuth(context: {
+	getAuth?: () => Promise<ProviderRequestAuth>;
+	getApiKey: () => Promise<string | undefined>;
+	model?: { baseUrl?: string };
+}): Promise<ProviderRequestAuth> {
+	if (context.getAuth) return await context.getAuth();
+	const apiKey = await context.getApiKey();
+	return {
+		...(apiKey !== undefined ? { apiKey } : {}),
+		...(context.model?.baseUrl !== undefined ? { baseUrl: context.model.baseUrl } : {}),
+	};
+}
+
+/** Test resolved headers case-insensitively, including explicit null removals. */
+export function authDefinesHeader(auth: ProviderRequestAuth, name: string): boolean {
+	const expected = name.toLowerCase();
+	return Object.keys(auth.headers ?? {}).some((candidate) => candidate.toLowerCase() === expected);
+}
+
+/** Apply Pi-resolved request headers over adapter defaults. */
+export function mergeDiagnosticHeaders(auth: ProviderRequestAuth, defaults: Record<string, string> = {}): Headers {
+	const headers = new Headers(defaults);
+	for (const [name, value] of Object.entries(auth.headers ?? {})) {
+		if (value === null) headers.delete(name);
+		else headers.set(name, value);
+	}
+	return headers;
+}
+
+function httpUrl(value: string | undefined): URL | undefined {
+	if (!value) return undefined;
+	try {
+		const parsed = new URL(value);
+		return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Match an effective model endpoint to a trusted origin; absent model context preserves direct adapter use. */
+export function hasBaseUrlOrigin(baseUrl: string | undefined, expectedUrl: string): boolean {
+	if (baseUrl === undefined) return true;
+	const actual = httpUrl(baseUrl);
+	const expected = httpUrl(expectedUrl);
+	return actual !== undefined && expected !== undefined && actual.origin === expected.origin;
+}
+
+/** Resolve a provider-relative diagnostic path without changing the effective endpoint origin. */
+export function appendBaseUrlPath(
+	baseUrl: string | undefined,
+	path: string,
+	fallbackBaseUrl?: string,
+): string | undefined {
+	const parsed = httpUrl(baseUrl) ?? httpUrl(fallbackBaseUrl);
+	if (!parsed) return undefined;
+	const suffix = path.replace(/^\/+/, "");
+	parsed.pathname = `${parsed.pathname.replace(/\/+$/, "")}/${suffix}`;
+	parsed.search = "";
+	parsed.hash = "";
+	return parsed.toString();
+}

package/core/host.ts

@@ -66,6 +66,7 @@ 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:
 			| {
@@ -85,10 +86,29 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 			refreshProviderRegistrations(pi, installedDefinition.definition.providers, runtime, snapshot);
 		};
 		const officialPricing = runtime.enableOfficialPricingFallback
-			? fetchOfficialPricingForHost(runtime, onBackgroundRefresh)
+			? 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 invalidateRuntime = (): void => {
 			lifecycleGeneration++;
 			installedDefinition = undefined;
@@ -412,6 +432,7 @@ 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) => {
@@ -426,6 +447,8 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 		});
 		pi.on("session_shutdown", () => {
 			disposed = true;
+			pricingRefreshController?.abort();
+			pricingRefreshController = undefined;
 			invalidateRuntime();
 			unsubscribeHostClaim();
 			unsubscribeBridge();
@@ -444,7 +467,7 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 
 function fetchOfficialPricingForHost(
 	runtime: PiProviderDependencies,
-	onBackgroundRefresh?: (snapshot: Record<string, OfficialModelMeta>) => void,
+	options: { allowNetwork?: boolean; signal?: AbortSignal } = {},
 ) {
 	return fetchOfficialPricing(
 		runtime.fetch,
@@ -456,8 +479,7 @@ function fetchOfficialPricingForHost(
 		{
 			cachePath:
 				runtime.officialPricingUrl === OPENROUTER_MODELS_URL ? runtime.openRouterMetadataCachePath : undefined,
-			background: runtime.officialPricingUrl === OPENROUTER_MODELS_URL,
-			onBackgroundRefresh,
+			...options,
 		},
 	);
 }

package/core/live-check-manager.ts

@@ -228,7 +228,8 @@ export class LiveCheckManager {
 			},
 		};
 		throwIfAborted(signal);
-		const stream = provider.streamSimple(ctx.model, context, options);
+		const requestModel = auth.baseUrl ? { ...ctx.model, baseUrl: auth.baseUrl } : ctx.model;
+		const stream = provider.streamSimple(requestModel, context, options);
 		let completed = false;
 		for await (const event of stream) {
 			if (event.type === "error") {

package/core/official-pricing.ts

@@ -48,6 +48,10 @@ export interface OfficialPricingFetchOptions {
 	background?: boolean;
 	/** Observe the completed background snapshot without delaying the initial caller. */
 	onBackgroundRefresh?: (snapshot: Record<string, OfficialModelMeta>) => void;
+	/** Read process/disk cache only and never start network access. */
+	allowNetwork?: boolean;
+	/** Cancel network access owned by the caller's lifecycle. */
+	signal?: AbortSignal;
 }
 
 interface PricingCacheEntry {
@@ -68,7 +72,7 @@ const pricingRequests = new Map<string, Promise<Record<string, OfficialModelMeta
 
 /** Default cache for OpenRouter metadata, not Pi's native model catalog. */
 export function getDefaultOpenRouterMetadataCachePath(agentDir: string): string {
-	return join(agentDir, "extensions", "pi-provider", "openrouter-model-metadata.json");
+	return agentDir.trim() === "" ? "" : join(agentDir, "extensions", "pi-provider", "openrouter-model-metadata.json");
 }
 
 function cloneCost(cost: ProviderCost): ProviderCost {
@@ -568,6 +572,7 @@ async function fetchOfficialPricingUncoalesced(
 	maxStaleMs: number,
 	now: () => number,
 	cachePath?: string,
+	externalSignal?: AbortSignal,
 ): Promise<Record<string, OfficialModelMeta>> {
 	const persisted = await readPersistedPricingCache(cachePath, pricingUrl);
 	const allowPersistedStale = persisted !== undefined;
@@ -581,12 +586,16 @@ async function fetchOfficialPricingUncoalesced(
 	}
 
 	try {
-		const result = await withDeadline(async (signal) => {
-			const response = await fetchFn(pricingUrl, { signal });
-			if (!response.ok) return { ok: false as const };
-			const payload = await response.json();
-			return { ok: true as const, parsed: parseOpenRouterModels(payload) };
-		}, timeoutMs);
+		const result = await withDeadline(
+			async (signal) => {
+				const response = await fetchFn(pricingUrl, { signal });
+				if (!response.ok) return { ok: false as const };
+				const payload = await response.json();
+				return { ok: true as const, parsed: parseOpenRouterModels(payload) };
+			},
+			timeoutMs,
+			externalSignal,
+		);
 		if (!result.ok) return staleCache(pricingUrl, now(), maxStaleMs, allowPersistedStale);
 		if (Object.keys(result.parsed).length > 0) {
 			const updatedAt = now();
@@ -663,15 +672,6 @@ export async function fetchOfficialPricing(
 	const cachedAge = getPricingCacheAge(pricingUrl, currentTime);
 	if (cachedAge !== undefined && cachedAge <= cacheTtlMs) return getPricingCache(pricingUrl);
 
-	const existing = pricingRequests.get(pricingUrl);
-	if (existing) {
-		if (options.background === true) {
-			observeBackgroundRefresh(existing, options.onBackgroundRefresh);
-			return getPricingCache(pricingUrl);
-		}
-		return existing;
-	}
-
 	if (options.cachePath) {
 		const persisted = await readPersistedPricingCache(options.cachePath, pricingUrl);
 		if (persisted !== undefined) {
@@ -684,7 +684,29 @@ export async function fetchOfficialPricing(
 		}
 	}
 
-	const request = startPricingRequest(fetchFn, pricingUrl, timeoutMs, cacheTtlMs, maxStaleMs, now, options.cachePath);
+	if (options.allowNetwork === false) return getPricingCache(pricingUrl);
+
+	const existing = options.signal === undefined ? pricingRequests.get(pricingUrl) : undefined;
+	if (existing) {
+		if (options.background === true) {
+			observeBackgroundRefresh(existing, options.onBackgroundRefresh);
+			return getPricingCache(pricingUrl);
+		}
+		return existing;
+	}
+
+	const request = options.signal
+		? fetchOfficialPricingUncoalesced(
+				fetchFn,
+				pricingUrl,
+				timeoutMs,
+				cacheTtlMs,
+				maxStaleMs,
+				now,
+				options.cachePath,
+				options.signal,
+			)
+		: startPricingRequest(fetchFn, pricingUrl, timeoutMs, cacheTtlMs, maxStaleMs, now, options.cachePath);
 	if (options.background === true) {
 		observeBackgroundRefresh(request, options.onBackgroundRefresh);
 		void request.catch(() => undefined);

package/core/preflight-manager.ts

@@ -1,15 +1,17 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { deriveCredentialType } from "./credential-type.ts";
 import { isValidTimeoutMs, withDeadline } from "./deadline.ts";
+import { applyDiagnosticBaseUrl, type DiagnosticModelRegistry, resolveDiagnosticAuth } from "./diagnostic-auth.ts";
 import { isProviderDataError, ProviderDataError } from "./errors.ts";
+import type { ProviderRequestAuth } from "./types.ts";
 
 export type PreflightModel = NonNullable<ExtensionContext["model"]>;
 
-type ModelRegistry = ExtensionContext["modelRegistry"];
-
 export interface PreflightContext {
 	fetch: typeof globalThis.fetch;
 	getApiKey: () => Promise<string | undefined>;
+	/** Complete model-scoped request authentication resolved by Pi. */
+	getAuth?: () => Promise<ProviderRequestAuth>;
 	signal?: AbortSignal;
 	now: () => number;
 	model: PreflightModel;
@@ -32,12 +34,14 @@ export interface PreflightAdapter {
 	name: string;
 	cacheTtlMs: number;
 	requestTimeoutMs: number;
+	/** Return false when this endpoint cannot safely serve the effective model URL. */
+	supportsModel?: (model: PreflightModel) => boolean;
 	fetch(context: PreflightContext): Promise<PreflightSnapshot>;
 }
 
 export interface PreflightContextLike {
 	model: PreflightModel;
-	modelRegistry: Pick<ModelRegistry, "getApiKeyForProvider">;
+	modelRegistry: DiagnosticModelRegistry;
 	/** Optional non-secret credential metadata for provider-specific account labels. */
 	getCredentialMetadata?: () => unknown;
 }
@@ -182,20 +186,30 @@ export class PreflightManager {
 			const cancellation = new AbortController();
 			const generation = ++state.generation;
 			const promise = withDeadline(
-				(signal) =>
-					adapter.fetch({
+				async (signal) => {
+					const auth = await resolveDiagnosticAuth(ctx.model, ctx.modelRegistry);
+					const model = applyDiagnosticBaseUrl(ctx.model, auth);
+					if (adapter.supportsModel && !adapter.supportsModel(model)) {
+						throw new ProviderDataError(
+							"Preflight endpoint is unavailable for the effective model URL",
+							"unsupported",
+						);
+					}
+					return await adapter.fetch({
 						fetch: this.fetchFn,
-						getApiKey: () => ctx.modelRegistry.getApiKeyForProvider(adapter.providerId),
+						getApiKey: async () => auth.apiKey,
+						getAuth: async () => auth,
 						now: this.now,
 						signal,
-						model: ctx.model,
+						model,
 						...(ctx.getCredentialMetadata === undefined
 							? {}
 							: {
 									getCredentialMetadata: ctx.getCredentialMetadata,
 									getCredentialType: async () => deriveCredentialType(ctx.getCredentialMetadata?.()),
 								}),
-					}),
+					});
+				},
 				adapter.requestTimeoutMs,
 				cancellation.signal,
 			);
@@ -217,6 +231,11 @@ export class PreflightManager {
 			return "refreshed";
 		} catch (error) {
 			if (state.generation !== generation || isErrorNamed(error, "AbortError")) return "skipped";
+			if (isProviderDataError(error) && error.code === "unsupported") {
+				state.snapshot = undefined;
+				state.lastError = undefined;
+				return "skipped";
+			}
 			state.lastError = errorState(error);
 			if (state.lastError.code === "timeout") {
 				state.generation++;