@hyav/pi-provider 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 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).
+- Add Status and Preflight Adapters for Pi native providers Moonshot (Kimi) international and China platforms, and Hugging Face router (plan/credits via `whoami-v2`).
+- Report Moonshot balance currency by platform: USD for the international platform and CNY for the China platform.
+- Skip MiniMax Token Plan status: the documented `/coding_plan/remains` endpoint requires a web session cookie, not the API key, and its field semantics are known to be unreliable (see MiniMax-M2 issues #88 and #99).
+- Add first-batch catalog Preflight Adapters for Pi native providers: OpenAI, Anthropic, Mistral, NVIDIA NIM, and Cerebras.
+- Add a shared OpenAI-style catalog preflight helper (`createCatalogPreflightAdapter`).
+- Add Status and Preflight Adapters for Pi native providers: Anthropic (subscription extra usage), OpenRouter (key credits and free tier), Groq (rate-limit headers), xAI (rate-limit headers), and GitHub Copilot (Individual plan quotas).
+- Route Anthropic credentials by type: API keys (`sk-ant-api...`) use `x-api-key` for preflight catalog checks and default status without sending keys to subscription endpoints; OAuth tokens (`sk-ant-oat...`) query subscription usage and send `Authorization: Bearer`.
+- Parse compound duration strings (`2m59.56s`, `7.66s`, `250ms`, `1d`, `1h30m`) and bare seconds in rate-limit reset headers for Groq and xAI status adapters.
+- Expose the stored credential type (`oauth` vs `api_key`) to Status and Preflight Adapters through `getCredentialType()`.
+- Align Charm Hyper status adapter cache TTL with standard status adapters (60s).
+
 ## 0.1.3 - 2026-08-17
 
 - Discover user Adapter files under `<agent-dir>/extensions/pi-provider/` in addition to built-ins; user files load last and override same-ID built-ins.

package/README.md

@@ -14,6 +14,10 @@ A provider extension toolkit for [Pi](https://pi.dev). It registers LLM provider
 - Provider-first pricing metadata with optional OpenRouter completion and quality indicators
 - 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
+- Status/preflight adapters for Moonshot (Kimi) international and China platforms, and Hugging Face plan/credits
+- Status/preflight adapters for the Vercel AI Gateway (auth, catalog, and credits)
+- Catalog preflight adapters for the native Pi providers OpenAI, Anthropic, Mistral, NVIDIA NIM, and Cerebras
 
 ## Install
 
@@ -41,11 +45,14 @@ 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 |
 |---|---:|---|---|
 | `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/` |
 
 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.
@@ -63,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

@@ -14,6 +14,10 @@
 - 优先采用 Provider 价格元数据，并可由 OpenRouter 补全价格和质量指标
 - 显式诊断：缓存 `/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
+- Status/Preflight 适配覆盖 Moonshot（Kimi）国际/国内平台与 Hugging Face 套餐/额度
+- Status/Preflight 适配覆盖 Vercel AI Gateway（鉴权、模型目录与额度）
+- 目录 Preflight 适配覆盖 Pi 原生 Provider：OpenAI、Anthropic、Mistral、NVIDIA NIM、Cerebras
 
 ## 安装
 
@@ -41,11 +45,14 @@ pi install npm:@hyav/pi-provider
 
 使用 `/status refresh` 执行免费的端点、鉴权、目录和账户检查。只有明确接受一次真实模型请求及其可能产生的用量费用时，才使用 `/status check`。
 
+动态 Provider 的 API Key 引用环境变量时，如果这些变量和已存储凭据均未配置，将保留缓存或回退模型目录并跳过网络刷新，避免未配置的 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/` 下 |
 
 程序化集成可以通过 `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) 是权威依据。
@@ -63,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

@@ -0,0 +1,142 @@
+/** 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";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export interface CatalogPreflightConfig {
+	id: string;
+	providerId: string;
+	name: string;
+	modelsUrl: string;
+	/**
+	 * Key header name such as "x-goog-api-key" or "x-api-key". When set, the
+	 * key-only header is used. Defaults to Authorization Bearer.
+	 */
+	keyHeader?: string;
+	/**
+	 * Provider-specific authentication for dual-mode providers. When set it
+	 * decides the request auth headers from the resolved credential type.
+	 */
+	authHeaders?: (apiKey: string, credential: string | undefined) => Record<string, string>;
+	/** Additional static headers such as {"anthropic-version": "2023-06-01"}. */
+	headers?: Record<string, string>;
+	/** Filter for usable entries; defaults to accepting every record with a non-empty `id`. */
+	include?: (model: Record<string, unknown>) => boolean;
+	/** Credentials are required; when false (mock), the check drops "auth". */
+	requireAuth?: boolean;
+}
+
+export function createCatalogPreflightAdapter(
+	config: CatalogPreflightConfig,
+	requestTimeoutMs: number,
+): PreflightAdapter {
+	return {
+		id: config.id,
+		providerId: config.providerId,
+		name: config.name,
+		cacheTtlMs: 30_000,
+		requestTimeoutMs,
+		async fetch(context) {
+			const auth = await getContextAuth(context);
+			const apiKey = auth.apiKey;
+			const credential = context.getCredentialType
+				? await context.getCredentialType().catch(() => undefined)
+				: undefined;
+			const headers = mergeDiagnosticHeaders(auth, {
+				Accept: "application/json",
+				"Accept-Encoding": "identity",
+				...(config.headers ?? {}),
+			});
+			if (apiKey && apiKey !== "proxy-managed") {
+				if (config.authHeaders) {
+					for (const [name, value] of Object.entries(config.authHeaders(apiKey, credential))) {
+						if (!authDefinesHeader(auth, name)) headers.set(name, value);
+					}
+				} else if (config.keyHeader) {
+					if (!authDefinesHeader(auth, config.keyHeader)) headers.set(config.keyHeader, apiKey);
+				} else if (!authDefinesHeader(auth, "Authorization")) {
+					headers.set("Authorization", `Bearer ${apiKey}`);
+				}
+			}
+			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}`,
+					`http${response.status}`,
+					parseRetryAfter(response.headers.get("retry-after"), context.now()),
+					response.status,
+				);
+			}
+			let payload: unknown;
+			try {
+				payload = await response.json();
+			} catch {
+				throw new ProviderDataError(`${config.name} preflight returned invalid JSON`, "badjson");
+			}
+			if (!isRecord(payload) || !Array.isArray(payload.data)) {
+				throw new ProviderDataError(`${config.name} preflight returned invalid catalog data`, "badjson");
+			}
+			const modelIds = new Set(
+				payload.data
+					.filter(isRecord)
+					.filter((model) => config.include?.(model) ?? true)
+					.map((model) => (typeof model.id === "string" ? model.id.trim() : undefined))
+					.filter((id): id is string => id !== undefined && id !== ""),
+			);
+			const checks = config.requireAuth === false ? ["endpoint", "catalog"] : ["endpoint", "catalog", "auth"];
+			return {
+				passed: modelIds.has(context.model.id),
+				checks,
+				updatedAt: context.now(),
+				httpStatus: response.status,
+			};
+		},
+	};
+}
+
+/** Recognize the dependencies mock tag "mock" as a placeholder key. */
+export function isUsableApiKey(apiKey: string | undefined): apiKey is string {
+	return apiKey !== undefined && apiKey !== "" && apiKey !== "proxy-managed" && apiKey !== "mock";
+}
+
+export function collectCatalogIds(
+	payload: unknown,
+	include?: (model: Record<string, unknown>) => boolean,
+): Set<string> {
+	if (!isRecord(payload) || !Array.isArray(payload.data)) {
+		throw new ProviderDataError("Catalog response returned invalid catalog data", "badjson");
+	}
+	return new Set(
+		payload.data
+			.filter(isRecord)
+			.filter((model) => include?.(model) ?? true)
+			.map((model) => (typeof model.id === "string" ? model.id.trim() : undefined))
+			.filter((id): id is string => id !== undefined && id !== ""),
+	);
+}
+
+/**
+ * Workspace endpoint selected from the model's own baseUrl. Returns undefined
+ * when the convention cannot be resolved (e.g. Anthropic base without /v1).
+ */
+export function workspaceModelsUrl(modelBaseUrl: string | undefined): string | undefined {
+	if (!modelBaseUrl) return undefined;
+	const trimmed = modelBaseUrl.replace(/\/+$/, "");
+	if (trimmed.startsWith("https://api.anthropic.com")) return `${trimmed}/v1/models`;
+	if (trimmed.includes("/v1")) return `${trimmed}/models`;
+	return undefined;
+}

package/core/credential-type.ts

@@ -0,0 +1,13 @@
+/** Non-secret credential type shared across the Status and Preflight managers. */
+
+export function deriveCredentialType(metadata: unknown): string | undefined {
+	try {
+		if (metadata !== null && typeof metadata === "object" && "type" in metadata) {
+			const value = (metadata as { type?: unknown }).type;
+			return typeof value === "string" ? value : undefined;
+		}
+	} catch {
+		// Credential metadata must never break status or preflight rendering.
+	}
+	return undefined;
+}

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);