@hyav/pi-provider 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 This file is the authoritative user-facing release history for `@hyav/pi-provider`.
 
+## 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
 
@@ -46,6 +50,7 @@ Use `/status refresh` for free endpoint, authentication, catalog, and account ch
 | 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.

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
 
 ## 安装
 
@@ -46,6 +50,7 @@ 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/` 下 |
 
 程序化集成可以通过 `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) 是权威依据。

package/core/catalog-preflight.ts

@@ -0,0 +1,130 @@
+/** Shared helpers for Provider-agnostic, OpenAI-style model-catalog checks. */
+
+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 apiKey = await context.getApiKey();
+			const credential = context.getCredentialType
+				? await context.getCredentialType().catch(() => undefined)
+				: undefined;
+			const headers: Record<string, string> = {
+				Accept: "application/json",
+				"Accept-Encoding": "identity",
+				...(config.headers ?? {}),
+			};
+			if (apiKey && apiKey !== "proxy-managed") {
+				if (config.authHeaders) {
+					Object.assign(headers, config.authHeaders(apiKey, credential));
+				} else if (config.keyHeader) {
+					headers[config.keyHeader] = apiKey;
+				} else {
+					headers.Authorization = `Bearer ${apiKey}`;
+				}
+			}
+			const response = await context.fetch(config.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/preflight-manager.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { deriveCredentialType } from "./credential-type.ts";
 import { isValidTimeoutMs, withDeadline } from "./deadline.ts";
 import { isProviderDataError, ProviderDataError } from "./errors.ts";
 
@@ -12,6 +13,10 @@ export interface PreflightContext {
 	signal?: AbortSignal;
 	now: () => number;
 	model: PreflightModel;
+	/** Optional non-secret credential metadata for provider-specific account labels. */
+	getCredentialMetadata?: () => unknown;
+	/** Optional non-secret credential type ("oauth" vs "api_key") for providers with dual auth modes. */
+	getCredentialType?: () => Promise<string | undefined>;
 }
 
 export interface PreflightSnapshot {
@@ -33,6 +38,8 @@ export interface PreflightAdapter {
 export interface PreflightContextLike {
 	model: PreflightModel;
 	modelRegistry: Pick<ModelRegistry, "getApiKeyForProvider">;
+	/** Optional non-secret credential metadata for provider-specific account labels. */
+	getCredentialMetadata?: () => unknown;
 }
 
 export interface PreflightErrorState {
@@ -182,6 +189,12 @@ export class PreflightManager {
 						now: this.now,
 						signal,
 						model: ctx.model,
+						...(ctx.getCredentialMetadata === undefined
+							? {}
+							: {
+									getCredentialMetadata: ctx.getCredentialMetadata,
+									getCredentialType: async () => deriveCredentialType(ctx.getCredentialMetadata?.()),
+								}),
 					}),
 				adapter.requestTimeoutMs,
 				cancellation.signal,

package/core/public-adapters.ts

@@ -18,6 +18,7 @@ export {
 	defineStatusExtension,
 	defineTunerExtension,
 } from "./adapter-extensions.ts";
+export { createCatalogPreflightAdapter } from "./catalog-preflight.ts";
 export { withDeadline } from "./deadline.ts";
 export { isProviderDataError, ProviderDataError } from "./errors.ts";
 export { createOpenCodeCatalogPreflightAdapter } from "./opencode-preflight.ts";

package/core/ratelimit-headers.ts

@@ -0,0 +1,72 @@
+/** Shared parsing for OpenAI-style `x-ratelimit-*` response headers. */
+
+export interface RateLimitWindow {
+	limit: number;
+	remaining: number;
+	resetAt?: number;
+}
+
+function numberValue(value: unknown): number | undefined {
+	if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : undefined;
+	}
+	return undefined;
+}
+
+const DURATION_PATTERN = /^((?:\d+(?:\.\d+)?(?:ms|[smhd]))+)$/i;
+const DURATION_PARTS = /(\d+(?:\.\d+)?)(ms|[smhd])/gi;
+const UNIT_SECONDS: Record<string, number> = { ms: 0.001, s: 1, m: 60, h: 3_600, d: 86_400 };
+
+export function durationSeconds(value: string): number | undefined {
+	const matched = DURATION_PATTERN.exec(value.trim());
+	if (!matched?.[1]) return undefined;
+	let total = 0;
+	for (const match of value.matchAll(DURATION_PARTS)) {
+		const amount = Number(match[1]);
+		if (!Number.isFinite(amount)) return undefined;
+		total += amount * (UNIT_SECONDS[match[2]!.toLowerCase()] ?? Number.NaN);
+		if (!Number.isFinite(total)) return undefined;
+	}
+	return total;
+}
+
+/**
+ * Reset hint in seconds. Providers use bare numbers, `7.66s`, and compound
+ * durations like Groq's `2m59.56s`; reset windows like `1d` also appear.
+ */
+export function resetSecondsFromHeader(value: string | null): number | undefined {
+	if (value === null || value.trim() === "") return undefined;
+	const trimmed = value.trim();
+	const duration = durationSeconds(trimmed);
+	if (duration === undefined) {
+		const bare = numberValue(trimmed);
+		if (bare === undefined || bare <= 0) return undefined;
+		return bare;
+	}
+	if (duration <= 0) return undefined;
+	return duration;
+}
+
+function parseWindow(headers: Headers, kind: "requests" | "tokens", now: number): RateLimitWindow | undefined {
+	const limit = numberValue(headers.get(`x-ratelimit-limit-${kind}`));
+	const remaining = numberValue(headers.get(`x-ratelimit-remaining-${kind}`));
+	if (limit === undefined || remaining === undefined || limit <= 0) return undefined;
+	const reset = resetSecondsFromHeader(headers.get(`x-ratelimit-reset-${kind}`) ?? headers.get("x-ratelimit-reset"));
+	return {
+		limit,
+		remaining,
+		...(reset !== undefined ? { resetAt: now + Math.round(reset * 1_000) } : {}),
+	};
+}
+
+export function parseRateLimitWindows(
+	headers: Headers,
+	now: number,
+): { requests?: RateLimitWindow; tokens?: RateLimitWindow } {
+	return {
+		requests: parseWindow(headers, "requests", now),
+		tokens: parseWindow(headers, "tokens", now),
+	};
+}

package/core/runtime.ts

@@ -46,10 +46,11 @@ function readProviderCredentialMetadata(
 ): unknown {
 	try {
 		const credential = readStoredCredential(provider);
-		if (credential?.type !== "oauth") return undefined;
+		const type = credential?.type;
+		if (type !== "oauth" && type !== "api_key") return undefined;
 		return {
-			type: "oauth",
-			...(typeof credential.teamName === "string" ? { teamName: credential.teamName } : {}),
+			type,
+			...(type === "oauth" && typeof credential?.teamName === "string" ? { teamName: credential.teamName } : {}),
 		};
 	} catch {
 		return undefined;
@@ -337,13 +338,19 @@ export function installPiProviderRuntime(
 		const { status, preflight, auth } = getStatusDetails(model, ctx);
 		let liveCheckRequested = false;
 		if ((mode === "refresh" || mode === "check") && auth.configured) {
+			const getCredentialMetadata = () =>
+				readProviderCredentialMetadata(model.provider, runtime.readStoredCredential);
 			const statusContext: StatusContextLike = {
 				model,
 				modelRegistry: ctx.modelRegistry,
 				getCredentialKey: () => ctx.modelRegistry.getApiKeyForProvider(model.provider),
-				getCredentialMetadata: () => readProviderCredentialMetadata(model.provider, runtime.readStoredCredential),
+				getCredentialMetadata,
+			};
+			const preflightContext: PreflightContextLike = {
+				model,
+				modelRegistry: ctx.modelRegistry,
+				getCredentialMetadata,
 			};
-			const preflightContext: PreflightContextLike = { model, modelRegistry: ctx.modelRegistry };
 			const refreshChecks: Array<Promise<unknown>> = [];
 			if (status) refreshChecks.push(statusManager.update(statusContext, { force: true }));
 			if (preflight) refreshChecks.push(preflightManager.update(preflightContext, { force: true }));

package/core/status-manager.ts

@@ -1,3 +1,4 @@
+import { deriveCredentialType } from "./credential-type.ts";
 import { isValidTimeoutMs, withDeadline } from "./deadline.ts";
 import { isProviderDataError, ProviderDataError } from "./errors.ts";
 import type {
@@ -226,7 +227,12 @@ export class StatusManager {
 					adapter.fetch({
 						fetch: this.fetchFn,
 						getApiKey: () => ctx.modelRegistry.getApiKeyForProvider(adapter.providerId),
-						...(ctx.getCredentialMetadata ? { getCredentialMetadata: ctx.getCredentialMetadata } : {}),
+						...(ctx.getCredentialMetadata === undefined
+							? {}
+							: {
+									getCredentialMetadata: ctx.getCredentialMetadata,
+									getCredentialType: async () => deriveCredentialType(ctx.getCredentialMetadata?.()),
+								}),
 						now: this.now,
 						signal,
 					}),

package/core/types.ts

@@ -147,6 +147,8 @@ export interface StatusContext {
 	getApiKey: () => Promise<string | undefined>;
 	/** Optional non-secret credential metadata for provider-specific account labels. */
 	getCredentialMetadata?: () => unknown;
+	/** Optional non-secret credential type ("oauth" vs "api_key") for providers with dual auth modes. */
+	getCredentialType?: () => Promise<string | undefined>;
 	signal?: AbortSignal;
 	now: () => number;
 }

package/index.ts

@@ -17,6 +17,7 @@ export {
 	defineStatusExtension,
 	defineTunerExtension,
 } from "./core/adapter-extensions.ts";
+export { createCatalogPreflightAdapter } from "./core/catalog-preflight.ts";
 export { withDeadline } from "./core/deadline.ts";
 export type { ProviderDataErrorLike } from "./core/errors.ts";
 export { isProviderDataError, ProviderDataError } from "./core/errors.ts";
@@ -74,6 +75,7 @@ export type {
 export { getPreflightKey, normalizePreflightSnapshot, PreflightManager } from "./core/preflight-manager.ts";
 export { applyPricingAdjustment, resolvePricingDetails } from "./core/pricing-adjustments.ts";
 export { normalizeProviderModels } from "./core/provider-registration.ts";
+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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyav/pi-provider",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "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",

package/preflight/anthropic.ts

@@ -0,0 +1,42 @@
+import type { PreflightAdapter } from "@hyav/pi-provider";
+import { definePreflightExtension } from "@hyav/pi-provider";
+import { createCatalogPreflightAdapter } from "../core/catalog-preflight.ts";
+import { isAnthropicApiKey, isAnthropicOAuthToken } from "../status/anthropic.ts";
+
+export const ANTHROPIC_MODELS_URL = "https://api.anthropic.com/v1/models";
+export const ANTHROPIC_API_VERSION = "2023-06-01";
+
+/**
+ * Anthropic accepts API keys via x-api-key and short-lived OAuth/WIF tokens via
+ * Authorization Bearer. Only the user's own default clause receives the key, no
+ * unknown/third-party endpoint.
+ */
+function anthropicAuthHeaders(apiKey: string, credential: string | undefined): Record<string, string> {
+	const isOAuth = credential === "oauth" ? !isAnthropicApiKey(apiKey) : isAnthropicOAuthToken(apiKey);
+	if (isOAuth) return { Authorization: `Bearer ${apiKey}` };
+	return { "x-api-key": apiKey };
+}
+
+export const anthropicPreflightAdapter: PreflightAdapter = createCatalogPreflightAdapter(
+	{
+		id: "anthropic-preflight",
+		providerId: "anthropic",
+		name: "Anthropic",
+		modelsUrl: ANTHROPIC_MODELS_URL,
+		headers: { "anthropic-version": ANTHROPIC_API_VERSION },
+		authHeaders: anthropicAuthHeaders,
+	},
+	8_000,
+);
+
+export function createAnthropicPreflightAdapter(requestTimeoutMs: number): PreflightAdapter {
+	return { ...anthropicPreflightAdapter, requestTimeoutMs };
+}
+
+const anthropicPreflightExtension = definePreflightExtension({
+	id: "anthropic-preflight",
+	providerId: "anthropic",
+	create: ({ statusRequestTimeoutMs }) => createAnthropicPreflightAdapter(statusRequestTimeoutMs),
+});
+
+export default anthropicPreflightExtension;

package/preflight/cerebras.ts

@@ -0,0 +1,27 @@
+import type { PreflightAdapter } from "@hyav/pi-provider";
+import { definePreflightExtension } from "@hyav/pi-provider";
+import { createCatalogPreflightAdapter } from "../core/catalog-preflight.ts";
+
+export const CEREBRAS_MODELS_URL = "https://api.cerebras.ai/v1/models";
+
+export const cerebrasPreflightAdapter: PreflightAdapter = createCatalogPreflightAdapter(
+	{
+		id: "cerebras-preflight",
+		providerId: "cerebras",
+		name: "Cerebras",
+		modelsUrl: CEREBRAS_MODELS_URL,
+	},
+	8_000,
+);
+
+export function createCerebrasPreflightAdapter(requestTimeoutMs: number): PreflightAdapter {
+	return { ...cerebrasPreflightAdapter, requestTimeoutMs };
+}
+
+const cerebrasPreflightExtension = definePreflightExtension({
+	id: "cerebras-preflight",
+	providerId: "cerebras",
+	create: ({ statusRequestTimeoutMs }) => createCerebrasPreflightAdapter(statusRequestTimeoutMs),
+});
+
+export default cerebrasPreflightExtension;

package/preflight/github-copilot.ts

@@ -0,0 +1,74 @@
+import type { PreflightAdapter } from "@hyav/pi-provider";
+import { definePreflightExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
+
+export const COPILOT_MODELS_URL = "https://api.individual.githubcopilot.com/models";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export const githubCopilotPreflightAdapter: PreflightAdapter = {
+	id: "github-copilot-preflight",
+	providerId: "github-copilot",
+	name: "GitHub Copilot",
+	cacheTtlMs: 30_000,
+	requestTimeoutMs: 8_000,
+	async fetch(context) {
+		const apiKey = await context.getApiKey();
+		if (!apiKey || apiKey === "proxy-managed") {
+			return { passed: false, checks: ["auth"], updatedAt: context.now() };
+		}
+		const response = await context.fetch(COPILOT_MODELS_URL, {
+			headers: {
+				Accept: "application/json",
+				"Accept-Encoding": "identity",
+				Authorization: `Bearer ${apiKey}`,
+				"User-Agent": "@hyav/pi-provider",
+			},
+			signal: context.signal,
+		});
+		if (!response.ok) {
+			throw new ProviderDataError(
+				`GitHub Copilot 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("GitHub Copilot preflight returned invalid JSON", "badjson");
+		}
+		if (!isRecord(payload) || !Array.isArray(payload.data)) {
+			throw new ProviderDataError("GitHub Copilot preflight returned invalid catalog data", "badjson");
+		}
+		const modelIds = new Set(
+			payload.data.flatMap((model) => {
+				if (!isRecord(model) || typeof model.id !== "string") return [];
+				const id = model.id.trim();
+				if (id === "") return [];
+				return [id];
+			}),
+		);
+		return {
+			passed: modelIds.has(context.model.id),
+			checks: ["endpoint", "catalog", "auth"],
+			updatedAt: context.now(),
+			httpStatus: response.status,
+		};
+	},
+};
+
+export function createGithubCopilotPreflightAdapter(requestTimeoutMs: number): PreflightAdapter {
+	return { ...githubCopilotPreflightAdapter, requestTimeoutMs };
+}
+
+const githubCopilotPreflightExtension = definePreflightExtension({
+	id: "github-copilot-preflight",
+	providerId: "github-copilot",
+	create: ({ statusRequestTimeoutMs }) => createGithubCopilotPreflightAdapter(statusRequestTimeoutMs),
+});
+
+export default githubCopilotPreflightExtension;

package/preflight/groq.ts

@@ -0,0 +1,72 @@
+import type { PreflightAdapter } from "@hyav/pi-provider";
+import { definePreflightExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
+import { GROQ_MODELS_URL } from "../status/groq.ts";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export const groqPreflightAdapter: PreflightAdapter = {
+	id: "groq-preflight",
+	providerId: "groq",
+	name: "Groq",
+	cacheTtlMs: 30_000,
+	requestTimeoutMs: 8_000,
+	async fetch(context) {
+		const apiKey = await context.getApiKey();
+		if (!apiKey || apiKey === "proxy-managed") {
+			return { passed: false, checks: ["auth"], updatedAt: context.now() };
+		}
+		const response = await context.fetch(GROQ_MODELS_URL, {
+			headers: {
+				Accept: "application/json",
+				"Accept-Encoding": "identity",
+				Authorization: `Bearer ${apiKey}`,
+			},
+			signal: context.signal,
+		});
+		if (!response.ok) {
+			throw new ProviderDataError(
+				`Groq 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("Groq preflight returned invalid JSON", "badjson");
+		}
+		if (!isRecord(payload) || !Array.isArray(payload.data)) {
+			throw new ProviderDataError("Groq preflight returned invalid catalog data", "badjson");
+		}
+		const activeIds = new Set(
+			payload.data.flatMap((model) => {
+				if (!isRecord(model) || typeof model.id !== "string") return [];
+				const id = model.id.trim();
+				if (id === "" || model.active === false) return [];
+				return [id];
+			}),
+		);
+		return {
+			passed: activeIds.has(context.model.id),
+			checks: ["endpoint", "auth", "catalog"],
+			updatedAt: context.now(),
+			httpStatus: response.status,
+		};
+	},
+};
+
+export function createGroqPreflightAdapter(requestTimeoutMs: number): PreflightAdapter {
+	return { ...groqPreflightAdapter, requestTimeoutMs };
+}
+
+const groqPreflightExtension = definePreflightExtension({
+	id: "groq-preflight",
+	providerId: "groq",
+	create: ({ statusRequestTimeoutMs }) => createGroqPreflightAdapter(statusRequestTimeoutMs),
+});
+
+export default groqPreflightExtension;

package/preflight/huggingface.ts

@@ -0,0 +1,27 @@
+import type { PreflightAdapter } from "@hyav/pi-provider";
+import { definePreflightExtension } from "@hyav/pi-provider";
+import { createCatalogPreflightAdapter } from "../core/catalog-preflight.ts";
+
+export const HF_ROUTER_MODELS_URL = "https://router.huggingface.co/v1/models";
+
+export const huggingFacePreflightAdapter: PreflightAdapter = createCatalogPreflightAdapter(
+	{
+		id: "huggingface-preflight",
+		providerId: "huggingface",
+		name: "Hugging Face",
+		modelsUrl: HF_ROUTER_MODELS_URL,
+	},
+	8_000,
+);
+
+export function createHuggingFacePreflightAdapter(requestTimeoutMs: number): PreflightAdapter {
+	return { ...huggingFacePreflightAdapter, requestTimeoutMs };
+}
+
+const huggingFacePreflightExtension = definePreflightExtension({
+	id: "huggingface-preflight",
+	providerId: "huggingface",
+	create: ({ statusRequestTimeoutMs }) => createHuggingFacePreflightAdapter(statusRequestTimeoutMs),
+});
+
+export default huggingFacePreflightExtension;