@hyav/pi-provider 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 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.
+- Run the provider runtime inside a single Jiti module graph behind a thin Pi entrypoint; inject the agent directory, stored credentials, and ANSI text wrapping.
+- Export the Adapter API through a Jiti-safe public entrypoint aliased as `@hyav/pi-provider`, aligned with the built-in Adapters as reference templates.
+- Resolve duplicate Adapter IDs and bindings to the latest registration with a warning instead of excluding all colliding entries.
+- Re-read modified Adapter files on `/reload` by clearing the Adapter module cache.
+- Restore the programmatic default OpenRouter metadata cache path under the resolved agent directory.
+
 ## 0.1.2 - 2026-08-17
 
 - Expose one Pi package entrypoint while preserving file-level Adapter discovery when `/reload` runs.

package/README.md

@@ -1,4 +1,4 @@
-# @hyav/pi-provider
+# pi-provider
 
 [简体中文](README.zh-CN.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,11 +50,33 @@ 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` |
-| `PI_CODING_AGENT_DIR` | No | `~/.pi/agent` | Changes Pi's agent directory; public OpenRouter metadata is cached under `<agent-dir>/pi-provider/` |
+| `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()`. Host packages with a custom capability root can call `createPiProviderExtension({ adapterRoot, dependencies })`. The source definition [`PiProviderDependencies`](core/runtime-config.ts) is authoritative.
+Programmatic integrations can configure pricing 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.
 
-Add or remove Adapter files under `@hyav/pi-provider`'s `providers/`, `status/`, `preflight/`, or `tuners/` directories, then run `/reload` to rediscover them without changing `index.ts`. Standalone trusted Adapter packages still declare their capability entries in their own Pi manifest. See the [adapter extension contract](https://github.com/hyav/pi-provider/blob/main/docs/adapter-extensions.md) for helpers, validation, conflicts, reload behavior, and lifecycle boundaries. The root [`index.ts`](index.ts) defines the public TypeScript exports.
+## Adapter discovery (file-level plug and play)
+
+Built-in Adapters ship inside the package and are always discovered. User Adapters live under Pi's resolved agent directory and are discovered too:
+
+```text
+<agent-dir>/extensions/pi-provider/
+  providers/   # provider Adapter files
+  status/      # status Adapter files
+  preflight/   # preflight Adapter files
+  tuners/      # tuner Adapter files
+```
+
+
+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).
+
+Adapter files import helpers and types from `@hyav/pi-provider` (aliased inside the loader):
+
+```ts
+import { defineProviderExtension } from "@hyav/pi-provider";
+```
+
+Adapter files must not runtime-import Pi's bundled packages (`@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, `@earendil-works/pi-ai`); type-only imports are fine. Runtime values such as the agent directory, stored credentials, and the ANSI text wrapper are injected by the Pi entrypoint. See the [adapter extension contract](https://github.com/hyav/pi-provider/blob/main/docs/adapter-extensions.md) for helpers, validation, conflicts, reload behavior, and lifecycle boundaries. The root [`index.ts`](index.ts) defines the public TypeScript exports.
 
 ## Before you use it
 

package/README.zh-CN.md

@@ -1,4 +1,4 @@
-# @hyav/pi-provider
+# pi-provider
 
 [English](README.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,11 +50,33 @@ pi install npm:@hyav/pi-provider
 | 名称 | 必需 | 默认值 | 作用 |
 |---|---:|---|---|
 | `HYPER_API_KEY` | Charm Hyper API Key 鉴权需要 | 无 | 为内置 `charm-hyper` Provider 提供凭据；OAuth 用户可以使用 `/login` |
-| `PI_CODING_AGENT_DIR` | 否 | `~/.pi/agent` | 修改 Pi agent 目录；公开 OpenRouter 元数据缓存在 `<agent-dir>/pi-provider/` 下 |
+| `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 和缓存路径；使用自定义 capability 根目录的 Host 包可以调用 `createPiProviderExtension({ adapterRoot, dependencies })`。源码定义 [`PiProviderDependencies`](core/runtime-config.ts) 是权威依据。
+程序化集成可以通过 `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) 是权威依据。
 
-在 `@hyav/pi-provider` 的 `providers/`、`status/`、`preflight/` 或 `tuners/` 目录增删 Adapter 文件后，执行 `/reload` 即可重新发现，无需修改 `index.ts`。独立的可信 Adapter 包仍通过自身 Pi manifest 声明 capability 入口。Helper、校验、冲突、reload 行为和生命周期边界见 [Adapter Extension 契约](https://github.com/hyav/pi-provider/blob/main/docs/adapter-extensions.zh-CN.md)。根目录 [`index.ts`](index.ts) 定义公开 TypeScript 导出。
+## Adapter 发现（文件级即插即用）
+
+内置 Adapter 随包发布，始终被扫描。用户 Adapter 放在 Pi 解析出的 agent 目录下，同样会被发现：
+
+```text
+<agent-dir>/extensions/pi-provider/
+  providers/   # Provider Adapter 文件
+  status/      # Status Adapter 文件
+  preflight/   # Preflight Adapter 文件
+  tuners/      # Tuner Adapter 文件
+```
+
+
+在目录中增删或修改文件后执行 `/reload` 即可重新发现，无需改动包；对现有文件的修改会重新从磁盘读取。用户 Adapter 在内置之后加载，因此同 ID 的用户文件会覆盖内置 Adapter（Host 保留最新注册并发出警告）。`createPiProviderExtension({ adapterRoot })` 用自定义根替换默认用户目录；内置目录始终被扫描。包内 `providers/`、`status/`、`preflight/` 下的内置 Adapter 就是采用这种写法的参考模板——复制一份改改即可（Charm Hyper 与 `preflight/openai-codex.ts` 还依赖包内私有辅助文件）。
+
+Adapter 文件从 `@hyav/pi-provider` 导入 helper 和类型（加载器内部做了别名映射）：
+
+```ts
+import { defineProviderExtension } from "@hyav/pi-provider";
+```
+
+Adapter 文件不得运行时导入 Pi 的内置包（`@earendil-works/pi-coding-agent`、`@earendil-works/pi-tui`、`@earendil-works/pi-ai`），仅 type-only 导入可以；agent 目录、存储凭据和 ANSI 文本包装器等运行时值由 Pi 入口注入。Helper、校验、冲突、reload 行为和生命周期边界见 [Adapter Extension 契约](https://github.com/hyav/pi-provider/blob/main/docs/adapter-extensions.zh-CN.md)。根目录 [`index.ts`](index.ts) 定义公开 TypeScript 导出。
 
 ## 使用须知
 

package/core/adapter-loader.ts

@@ -1,15 +1,53 @@
 import type { Dirent } from "node:fs";
 import { readdir } from "node:fs/promises";
-import { dirname, extname, join, relative } from "node:path";
+import { createRequire } from "node:module";
+import { dirname, extname, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { createJiti } from "jiti";
 
 const adapterDirectories = ["providers", "status", "preflight", "tuners"] as const;
-const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const defaultPackageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+/** Jiti-safe module that adapter files reach through the `@hyav/pi-provider` alias. */
+const publicAdaptersPath = join(defaultPackageRoot, "core", "public-adapters.ts");
 
 type AdapterExtensionFactory = (pi: ExtensionAPI) => void | Promise<void>;
 
+export interface AdapterRootOptions {
+	/** Package root containing built-in adapters; defaults to this package. */
+	packageRoot?: string;
+	/** Pi's resolved agent directory; user adapters are discovered under `<agentDir>/extensions/pi-provider`. */
+	agentDir?: string;
+	/** Explicit user adapter root; replaces the agentDir-based default when provided. */
+	userRoot?: string;
+}
+
+/** Built-in adapters always load first; user adapters load last so they can override. */
+export function resolveAdapterRoots(options: AdapterRootOptions): string[] {
+	const { packageRoot, agentDir, userRoot } = options;
+	const defaultUserRoot =
+		agentDir !== undefined && agentDir !== "" ? join(agentDir, "extensions", "pi-provider") : undefined;
+	const resolvedUserRoot = userRoot ?? defaultUserRoot;
+	const roots = [packageRoot ?? defaultPackageRoot];
+	if (resolvedUserRoot !== undefined) roots.push(resolvedUserRoot);
+	return roots;
+}
+
+/**
+ * Jiti's module cache is Node's global `require.cache`, so a reload would
+ * otherwise reuse previously loaded adapter modules without reading the disk.
+ * Drop every cached module under the adapter roots before each load so edits
+ * to existing adapter files take effect on `/reload`.
+ */
+function clearAdapterModuleCache(roots: string[]): void {
+	const require = createRequire(import.meta.url);
+	for (const key of Object.keys(require.cache)) {
+		if (roots.some((root) => key.startsWith(root.endsWith(sep) ? root : `${root}${sep}`))) {
+			delete require.cache[key];
+		}
+	}
+}
+
 function isAdapterFile(name: string): boolean {
 	if (name.endsWith(".d.ts")) return false;
 	return extname(name) === ".ts" || extname(name) === ".js";
@@ -37,17 +75,25 @@ async function discoverAdapterPaths(root: string): Promise<string[]> {
 	return paths.sort();
 }
 
-export async function loadPackageAdapterExtensions(pi: ExtensionAPI, root: string = packageRoot): Promise<void> {
-	const jiti = createJiti(import.meta.url, { moduleCache: false, tryNative: false });
-	for (const path of await discoverAdapterPaths(root)) {
-		try {
-			const factory = (await jiti.import(path, { default: true })) as unknown;
-			if (typeof factory !== "function") {
-				throw new TypeError("default export must be a Pi extension factory");
+export async function loadPackageAdapterExtensions(pi: ExtensionAPI, options: AdapterRootOptions = {}): Promise<void> {
+	const roots = resolveAdapterRoots(options);
+	clearAdapterModuleCache(roots);
+	const jiti = createJiti(import.meta.url, {
+		moduleCache: true,
+		tryNative: false,
+		alias: { "@hyav/pi-provider": publicAdaptersPath },
+	});
+	for (const root of roots) {
+		for (const path of await discoverAdapterPaths(root)) {
+			try {
+				const factory = (await jiti.import(path, { default: true })) as unknown;
+				if (typeof factory !== "function") {
+					throw new TypeError("default export must be a Pi extension factory");
+				}
+				await (factory as AdapterExtensionFactory)(pi);
+			} catch (error) {
+				warnAdapterLoadIssue(relative(root, path).replaceAll("\\", "/"), error);
 			}
-			await (factory as AdapterExtensionFactory)(pi);
-		} catch (error) {
-			warnAdapterLoadIssue(relative(root, path).replaceAll("\\", "/"), error);
 		}
 	}
 }

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/host.ts

@@ -148,10 +148,11 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 			const result: T[] = [];
 			for (const [id, group] of groups) {
 				if (group.length > 1) {
-					warnAdapterIssue(`excluded ${group.length} colliding ${label} entries for ${JSON.stringify(id)}`);
-					continue;
+					warnAdapterIssue(
+						`resolved ${group.length} colliding ${label} entries for ${JSON.stringify(id)} to the latest registration`,
+					);
 				}
-				result.push(group[0]!);
+				result.push(group[group.length - 1]!);
 			}
 			return result;
 		};

package/core/official-pricing.ts

@@ -1,7 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { withDeadline } from "./deadline.ts";
 import type { ModelQualityScore, ProviderCost, ProviderModel, ProviderModelDraft } from "./types.ts";
 
@@ -68,8 +67,8 @@ const pricingCache = new Map<string, PricingCacheEntry>();
 const pricingRequests = new Map<string, Promise<Record<string, OfficialModelMeta>>>();
 
 /** Default cache for OpenRouter metadata, not Pi's native model catalog. */
-export function getDefaultOpenRouterMetadataCachePath(): string {
-	return join(getAgentDir(), "pi-provider", "openrouter-model-metadata.json");
+export function getDefaultOpenRouterMetadataCachePath(agentDir: string): string {
+	return join(agentDir, "extensions", "pi-provider", "openrouter-model-metadata.json");
 }
 
 function cloneCost(cost: ProviderCost): ProviderCost {

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

@@ -0,0 +1,47 @@
+/**
+ * Jiti-safe public entrypoint for user adapter files discovered from the
+ * adapter roots. `loadPackageAdapterExtensions` aliases `@hyav/pi-provider`
+ * to this module so adapter files can import the same helpers and types the
+ * built-in adapters use, without resolving Pi's bundled runtime packages.
+ */
+
+export type {
+	AdapterExtensionContext,
+	PreflightExtensionDefinition,
+	ProviderExtensionDefinition,
+	StatusExtensionDefinition,
+	TunerExtensionDefinition,
+} from "./adapter-extensions.ts";
+export {
+	definePreflightExtension,
+	defineProviderExtension,
+	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";
+export type {
+	PreflightAdapter,
+	PreflightContextLike,
+	PreflightModel,
+	PreflightSnapshot,
+} from "./preflight-manager.ts";
+export { normalizeProviderModels } from "./provider-registration.ts";
+export { parseRetryAfter } from "./retry-after.ts";
+export type { StatusContextLike } from "./status-manager.ts";
+export type {
+	ActiveModel,
+	ModelCatalogStatus,
+	ProviderAdapter,
+	ProviderModel,
+	ProviderModelDraft,
+	ProviderRefreshContext,
+	StatusAdapter,
+	StatusContext,
+	StatusEntry,
+	StatusSnapshot,
+	StoredCredentialLike,
+	TunerContext,
+} from "./types.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),
+	};
+}