@hyav/pi-provider 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 This file is the authoritative user-facing release history for `@hyav/pi-provider`.
 
+## 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)
 
@@ -46,11 +46,32 @@ 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/` |
+| `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)
 
@@ -46,11 +46,32 @@ 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/` 下 |
+| `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/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/public-adapters.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 { 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/runtime-config.ts

@@ -1,8 +1,10 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { isValidTimeoutMs } from "./deadline.ts";
 import type { PiProviderDefinition } from "./definition.ts";
 import { getDefaultOpenRouterMetadataCachePath, OPENROUTER_MODELS_URL } from "./official-pricing.ts";
 import { validatePricingPolicy } from "./pricing-adjustments.ts";
-import type { ProviderPricingPolicy } from "./types.ts";
+import type { ProviderPricingPolicy, StoredCredentialLike } from "./types.ts";
 
 export interface PiProviderDependencies {
 	fetch: typeof globalThis.fetch;
@@ -14,8 +16,14 @@ export interface PiProviderDependencies {
 	officialPricingTimeoutMs: number;
 	officialPricingCacheTtlMs: number;
 	officialPricingMaxStaleMs: number;
+	/** Resolved Pi agent directory; empty disables disk persistence of pricing metadata. */
+	agentDir: string;
 	/** Persistent cache for OpenRouter metadata used by the pricing fallback. */
 	openRouterMetadataCachePath: string;
+	/** Read Pi's stored credential metadata; injected by the Pi entrypoint. */
+	readStoredCredential: (providerId: string) => StoredCredentialLike | undefined;
+	/** Wrap ANSI-aware text to a render width; injected by the Pi entrypoint. */
+	wrapTextWithAnsi: (text: string, width: number) => string[];
 	enableOfficialPricingFallback: boolean;
 	/** Optional Pi Provider-level price policies keyed by Provider ID. */
 	pricingPolicies?: Record<string, ProviderPricingPolicy>;
@@ -23,7 +31,68 @@ export interface PiProviderDependencies {
 
 export type PiProviderLoader = (runtime: PiProviderDependencies) => Promise<PiProviderDefinition>;
 
-const defaultDependencies: PiProviderDependencies = {
+/**
+ * Resolve Pi's agent directory without importing Pi's bundled packages, so the
+ * Jiti module graph and programmatic consumers share the same default. Mirrors
+ * Pi's `getAgentDir()`: `PI_CODING_AGENT_DIR` wins, `~/` expands to the home
+ * directory, and the fallback is `~/.pi/agent`.
+ */
+export function resolveDefaultAgentDir(): string {
+	const configured = process.env.PI_CODING_AGENT_DIR;
+	const raw =
+		configured !== undefined && configured.trim() !== "" ? configured.trim() : join(homedir(), ".pi", "agent");
+	if (raw === "~") return homedir();
+	if (raw.startsWith("~/")) return join(homedir(), raw.slice(2));
+	return raw;
+}
+
+/** Degraded fallback used only when the Pi entrypoint does not inject the real wrapper. */
+const WIDE_CHAR_RANGES: Array<[number, number]> = [
+	[0x1100, 0x115f],
+	[0x2329, 0x232a],
+	[0x2e80, 0xa4cf],
+	[0xac00, 0xd7a3],
+	[0xf900, 0xfaff],
+	[0xfe30, 0xfe4f],
+	[0xff00, 0xff60],
+	[0xffe0, 0xffe6],
+	[0x1f300, 0x1f64f],
+	[0x1f900, 0x1f9ff],
+	[0x20000, 0x2fffd],
+	[0x30000, 0x3fffd],
+];
+
+function displayWidth(text: string): number {
+	let width = 0;
+	for (const ch of text) {
+		const code = ch.codePointAt(0) ?? 0;
+		const wide = WIDE_CHAR_RANGES.some(([start, end]) => code >= start && code <= end);
+		width += wide ? 2 : 1;
+	}
+	return width;
+}
+
+function defaultWrapTextWithAnsi(text: string, width: number): string[] {
+	if (width <= 0) return [text];
+	const plain = text.replace(/\u001b\[[0-9;]*m/g, "");
+	if (displayWidth(plain) <= width) return [text];
+	const chunks: string[] = [];
+	let chunk = "";
+	for (const ch of plain) {
+		if (chunk !== "" && displayWidth(chunk) + displayWidth(ch) > width) {
+			chunks.push(chunk);
+			chunk = ch;
+		} else {
+			chunk += ch;
+		}
+	}
+	if (chunk !== "") chunks.push(chunk);
+	return chunks;
+}
+
+type DefaultDependencies = Omit<PiProviderDependencies, "agentDir" | "openRouterMetadataCachePath">;
+
+const defaultDependencies: DefaultDependencies = {
 	fetch: globalThis.fetch,
 	now: Date.now,
 	modelDiscoveryTimeoutMs: 3_000,
@@ -33,13 +102,22 @@ const defaultDependencies: PiProviderDependencies = {
 	officialPricingTimeoutMs: 3_000,
 	officialPricingCacheTtlMs: 60 * 60 * 1_000,
 	officialPricingMaxStaleMs: 24 * 60 * 60 * 1_000,
-	openRouterMetadataCachePath: getDefaultOpenRouterMetadataCachePath(),
+	readStoredCredential: () => undefined,
+	wrapTextWithAnsi: defaultWrapTextWithAnsi,
 	enableOfficialPricingFallback: true,
 	pricingPolicies: {},
 };
 
-export function getDefaultPiProviderDependencies(): PiProviderDependencies {
-	return { ...defaultDependencies };
+/**
+ * Programmatic defaults keep the resolved agent directory and its pricing cache
+ * path. The Pi entrypoint overrides `agentDir` with Pi's own resolution.
+ */
+export function getDefaultPiProviderDependencies(agentDir = resolveDefaultAgentDir()): PiProviderDependencies {
+	return {
+		...defaultDependencies,
+		agentDir,
+		openRouterMetadataCachePath: getDefaultOpenRouterMetadataCachePath(agentDir),
+	};
 }
 
 export function validatePiProviderDependencies(runtime: PiProviderDependencies): void {
@@ -64,8 +142,14 @@ export function validatePiProviderDependencies(runtime: PiProviderDependencies):
 	if (typeof runtime.officialPricingUrl !== "string" || runtime.officialPricingUrl.trim() === "") {
 		throw new Error("Pi Provider officialPricingUrl must be a non-empty string");
 	}
-	if (typeof runtime.openRouterMetadataCachePath !== "string" || runtime.openRouterMetadataCachePath.trim() === "") {
-		throw new Error("Pi Provider openRouterMetadataCachePath must be a non-empty path");
+	if (typeof runtime.openRouterMetadataCachePath !== "string") {
+		throw new Error("Pi Provider openRouterMetadataCachePath must be a string");
+	}
+	if (typeof runtime.readStoredCredential !== "function") {
+		throw new Error("Pi Provider readStoredCredential must be a function");
+	}
+	if (typeof runtime.wrapTextWithAnsi !== "function") {
+		throw new Error("Pi Provider wrapTextWithAnsi must be a function");
 	}
 	if (typeof runtime.enableOfficialPricingFallback !== "boolean") {
 		throw new Error("Pi Provider enableOfficialPricingFallback must be a boolean");
@@ -88,7 +172,7 @@ export function validatePiProviderDependencies(runtime: PiProviderDependencies):
 export function resolvePiProviderDependencies(
 	dependencies: Partial<PiProviderDependencies> = {},
 ): PiProviderDependencies {
-	const runtime = { ...defaultDependencies, ...dependencies };
+	const runtime = { ...getDefaultPiProviderDependencies(), ...dependencies };
 	if (runtime.pricingPolicies === undefined) runtime.pricingPolicies = {};
 	validatePiProviderDependencies(runtime);
 	return runtime;

package/core/runtime-entry.ts

@@ -0,0 +1,26 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadPackageAdapterExtensions } from "./adapter-loader.ts";
+import { createPiProviderHost } from "./host.ts";
+import type { PiProviderDependencies } from "./runtime-config.ts";
+import type { StoredCredentialLike } from "./types.ts";
+
+/** Runtime values resolved by the Pi-loaded entrypoint and injected into the Jiti graph. */
+export interface PiProviderEntry {
+	agentDir: string;
+	readStoredCredential: (providerId: string) => StoredCredentialLike | undefined;
+	wrapTextWithAnsi: (text: string, width: number) => string[];
+	adapterRoot?: string;
+	dependencies?: Partial<PiProviderDependencies>;
+}
+
+/** Runs the Pi Provider host and adapter discovery inside a single Jiti module graph. */
+export async function runPiProviderEntry(pi: ExtensionAPI, entry: PiProviderEntry): Promise<void> {
+	const piProviderHost = createPiProviderHost({
+		agentDir: entry.agentDir,
+		readStoredCredential: entry.readStoredCredential,
+		wrapTextWithAnsi: entry.wrapTextWithAnsi,
+		...entry.dependencies,
+	});
+	piProviderHost(pi);
+	await loadPackageAdapterExtensions(pi, { agentDir: entry.agentDir, userRoot: entry.adapterRoot });
+}

package/core/runtime.ts

@@ -1,6 +1,4 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { readStoredCredential } from "@earendil-works/pi-coding-agent";
-import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import type { PiProviderDefinition } from "./definition.ts";
 import { validatePiProviderDefinition } from "./definition.ts";
 import { LiveCheckManager, type LiveCheckResult } from "./live-check-manager.ts";
@@ -33,6 +31,7 @@ import type {
 	ProviderCost,
 	ProviderModelDraft,
 	ProviderModelMetadata,
+	StoredCredentialLike,
 } from "./types.ts";
 
 type ActiveModel = NonNullable<ExtensionContext["model"]>;
@@ -41,7 +40,10 @@ type StatusNotificationContext = Pick<ExtensionContext, "modelRegistry" | "ui">
 };
 const STATUS_WIDGET_KEY = "pi-provider-status";
 
-function readProviderCredentialMetadata(provider: string): unknown {
+function readProviderCredentialMetadata(
+	provider: string,
+	readStoredCredential: (providerId: string) => StoredCredentialLike | undefined,
+): unknown {
 	try {
 		const credential = readStoredCredential(provider);
 		if (credential?.type !== "oauth") return undefined;
@@ -59,7 +61,11 @@ function clearTransientStatus(ctx: Pick<ExtensionContext, "ui">): void {
 	ctx.ui.setWidget(STATUS_WIDGET_KEY, undefined);
 }
 
-function showTransientStatus(message: string, ctx: StatusNotificationContext): boolean {
+function showTransientStatus(
+	message: string,
+	ctx: StatusNotificationContext,
+	wrapTextWithAnsi: (text: string, width: number) => string[],
+): boolean {
 	if ((ctx.mode !== "tui" && ctx.mode !== "rpc") || typeof ctx.ui.setWidget !== "function") return false;
 	// RPC cannot render component factories, so keep its plain text protocol unchanged.
 	if (ctx.mode === "rpc") {
@@ -301,7 +307,7 @@ export function installPiProviderRuntime(
 		);
 		const message = report.report;
 		if (report.warningLevel !== "hard") {
-			statusPresentationVisible = showTransientStatus(message, ctx);
+			statusPresentationVisible = showTransientStatus(message, ctx, runtime.wrapTextWithAnsi);
 			if (!statusPresentationVisible) ctx.ui.notify(message, "info");
 			return;
 		}
@@ -335,7 +341,7 @@ export function installPiProviderRuntime(
 				model,
 				modelRegistry: ctx.modelRegistry,
 				getCredentialKey: () => ctx.modelRegistry.getApiKeyForProvider(model.provider),
-				getCredentialMetadata: () => readProviderCredentialMetadata(model.provider),
+				getCredentialMetadata: () => readProviderCredentialMetadata(model.provider, runtime.readStoredCredential),
 			};
 			const preflightContext: PreflightContextLike = { model, modelRegistry: ctx.modelRegistry };
 			const refreshChecks: Array<Promise<unknown>> = [];

package/core/types.ts

@@ -22,6 +22,16 @@ export interface ModelMetadataStatus {
 	source?: string;
 }
 
+/**
+ * Narrow credential shape shared across Pi's isolated extension module contexts.
+ * The full Credential type comes from Pi's bundled AI package; consumers of
+ * injected credential readers must not rely on `instanceof` or extra fields.
+ */
+export interface StoredCredentialLike {
+	readonly type?: string;
+	readonly teamName?: string;
+}
+
 export interface ModelFieldSources {
 	contextWindow?: ModelFieldSource;
 	maxTokens?: ModelFieldSource;

package/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadPackageAdapterExtensions } from "./core/adapter-loader.ts";
-import { createPiProviderHost } from "./core/host.ts";
+import { getAgentDir, readStoredCredential } from "@earendil-works/pi-coding-agent";
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { createJiti } from "jiti";
 import type { PiProviderDependencies } from "./core/runtime-config.ts";
 
 export type {
@@ -16,6 +17,7 @@ export {
 	defineStatusExtension,
 	defineTunerExtension,
 } from "./core/adapter-extensions.ts";
+export { withDeadline } from "./core/deadline.ts";
 export type { ProviderDataErrorLike } from "./core/errors.ts";
 export { isProviderDataError, ProviderDataError } from "./core/errors.ts";
 export type {
@@ -59,6 +61,7 @@ export {
 	parseOpenRouterPricing,
 	setPricingCache,
 } from "./core/official-pricing.ts";
+export { createOpenCodeCatalogPreflightAdapter } from "./core/opencode-preflight.ts";
 export type {
 	PreflightAdapter,
 	PreflightContext,
@@ -70,6 +73,8 @@ export type {
 } from "./core/preflight-manager.ts";
 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 { parseRetryAfter } from "./core/retry-after.ts";
 export type { StatusDiagnostics, StatusErrorState } from "./core/status-manager.ts";
 export { normalizeStatusSnapshot, StatusManager } from "./core/status-manager.ts";
 export { applyTunerAdapters, sortTunerAdapters } from "./core/tuner-manager.ts";
@@ -109,7 +114,7 @@ export type {
 } from "./core/types.ts";
 
 export interface PiProviderExtensionOptions {
-	/** Package root containing providers, status, preflight, and tuners directories. */
+	/** User adapter root; replaces the default `<agentDir>/pi-provider` directory. */
 	adapterRoot?: string;
 	/** Host runtime dependency overrides. */
 	dependencies?: Partial<PiProviderDependencies>;
@@ -119,10 +124,27 @@ export interface PiProviderExtensionOptions {
 export function createPiProviderExtension(
 	options: PiProviderExtensionOptions = {},
 ): (pi: ExtensionAPI) => Promise<void> {
-	const piProviderHost = createPiProviderHost(options.dependencies);
 	return async (pi) => {
-		piProviderHost(pi);
-		await loadPackageAdapterExtensions(pi, options.adapterRoot);
+		const jiti = createJiti(import.meta.url, { moduleCache: true, tryNative: false });
+		const { runPiProviderEntry } = (await jiti.import("./core/runtime-entry.ts")) as {
+			runPiProviderEntry: (
+				pi: ExtensionAPI,
+				entry: {
+					agentDir: string;
+					readStoredCredential: typeof readStoredCredential;
+					wrapTextWithAnsi: typeof wrapTextWithAnsi;
+					adapterRoot?: string;
+					dependencies?: Partial<PiProviderDependencies>;
+				},
+			) => Promise<void>;
+		};
+		await runPiProviderEntry(pi, {
+			agentDir: getAgentDir(),
+			readStoredCredential,
+			wrapTextWithAnsi,
+			adapterRoot: options.adapterRoot,
+			dependencies: options.dependencies,
+		});
 	};
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyav/pi-provider",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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/charm-hyper.ts

@@ -1,7 +1,5 @@
-import { definePreflightExtension } from "../core/adapter-extensions.ts";
-import { ProviderDataError } from "../core/errors.ts";
-import type { PreflightAdapter } from "../core/preflight-manager.ts";
-import { parseRetryAfter } from "../core/retry-after.ts";
+import type { PreflightAdapter } from "@hyav/pi-provider";
+import { definePreflightExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
 import { hyperJsonHeaders } from "../providers/charm-hyper/constants.ts";
 import { HYPER_MODELS_URL, HYPER_PROVIDER_URL, parseHyperModels } from "../providers/charm-hyper.ts";
 

package/preflight/deepseek.ts

@@ -1,7 +1,5 @@
-import { definePreflightExtension } from "../core/adapter-extensions.ts";
-import { ProviderDataError } from "../core/errors.ts";
-import type { PreflightAdapter } from "../core/preflight-manager.ts";
-import { parseRetryAfter } from "../core/retry-after.ts";
+import type { PreflightAdapter } from "@hyav/pi-provider";
+import { definePreflightExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
 
 export const DEEPSEEK_MODELS_URL = "https://api.deepseek.com/models";
 

package/preflight/google.ts

@@ -1,7 +1,5 @@
-import { definePreflightExtension } from "../core/adapter-extensions.ts";
-import { ProviderDataError } from "../core/errors.ts";
-import type { PreflightAdapter } from "../core/preflight-manager.ts";
-import { parseRetryAfter } from "../core/retry-after.ts";
+import type { PreflightAdapter } from "@hyav/pi-provider";
+import { definePreflightExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
 
 export const GOOGLE_MODELS_URL = "https://generativelanguage.googleapis.com/v1beta/models";
 

package/preflight/openai-codex.ts

@@ -1,7 +1,5 @@
-import { definePreflightExtension } from "../core/adapter-extensions.ts";
-import { ProviderDataError } from "../core/errors.ts";
-import type { PreflightAdapter } from "../core/preflight-manager.ts";
-import { parseRetryAfter } from "../core/retry-after.ts";
+import type { PreflightAdapter } from "@hyav/pi-provider";
+import { definePreflightExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
 import { extractCodexAccountId } from "../status/openai-codex.ts";
 
 export const CODEX_MODELS_URL = "https://chatgpt.com/backend-api/codex/models";

package/preflight/opencode-go.ts

@@ -1,6 +1,5 @@
-import { definePreflightExtension } from "../core/adapter-extensions.ts";
-import { createOpenCodeCatalogPreflightAdapter } from "../core/opencode-preflight.ts";
-import type { PreflightAdapter } from "../core/preflight-manager.ts";
+import type { PreflightAdapter } from "@hyav/pi-provider";
+import { createOpenCodeCatalogPreflightAdapter, definePreflightExtension } from "@hyav/pi-provider";
 
 export const OPENCODE_GO_MODELS_URL = "https://opencode.ai/zen/go/v1/models";
 

package/preflight/opencode.ts

@@ -1,6 +1,5 @@
-import { definePreflightExtension } from "../core/adapter-extensions.ts";
-import { createOpenCodeCatalogPreflightAdapter } from "../core/opencode-preflight.ts";
-import type { PreflightAdapter } from "../core/preflight-manager.ts";
+import type { PreflightAdapter } from "@hyav/pi-provider";
+import { createOpenCodeCatalogPreflightAdapter, definePreflightExtension } from "@hyav/pi-provider";
 
 export const OPENCODE_MODELS_URL = "https://opencode.ai/zen/v1/models";
 

package/providers/charm-hyper.ts

@@ -1,7 +1,3 @@
-import { defineProviderExtension } from "../core/adapter-extensions.ts";
-import { withDeadline } from "../core/deadline.ts";
-import { isProviderDataError, ProviderDataError } from "../core/errors.ts";
-import { normalizeProviderModels } from "../core/provider-registration.ts";
 import type {
 	ModelCatalogStatus,
 	ProviderAdapter,
@@ -9,7 +5,14 @@ import type {
 	ProviderModelDraft,
 	ProviderRefreshContext,
 	ThinkingLevel,
-} from "../core/types.ts";
+} from "@hyav/pi-provider";
+import {
+	defineProviderExtension,
+	isProviderDataError,
+	normalizeProviderModels,
+	ProviderDataError,
+	withDeadline,
+} from "@hyav/pi-provider";
 import { HYPER_BASE_URL, HYPER_USER_AGENT, hyperJsonHeaders } from "./charm-hyper/constants.ts";
 import { createCharmHyperOAuth } from "./charm-hyper/oauth.ts";
 

package/status/charm-hyper.ts

@@ -1,7 +1,5 @@
-import { defineStatusExtension } from "../core/adapter-extensions.ts";
-import { ProviderDataError } from "../core/errors.ts";
-import { parseRetryAfter } from "../core/retry-after.ts";
-import type { StatusAdapter, StatusSnapshot } from "../core/types.ts";
+import type { StatusAdapter, StatusSnapshot } from "@hyav/pi-provider";
+import { defineStatusExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
 import { hyperJsonHeaders } from "../providers/charm-hyper/constants.ts";
 
 const CREDITS_URL = "https://hyper.charm.land/v1/credits";

package/status/deepseek.ts

@@ -1,7 +1,5 @@
-import { defineStatusExtension } from "../core/adapter-extensions.ts";
-import { ProviderDataError } from "../core/errors.ts";
-import { parseRetryAfter } from "../core/retry-after.ts";
-import type { StatusAdapter, StatusSnapshot } from "../core/types.ts";
+import type { StatusAdapter, StatusSnapshot } from "@hyav/pi-provider";
+import { defineStatusExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
 
 export const DEEPSEEK_BALANCE_URL = "https://api.deepseek.com/user/balance";
 

package/status/openai-codex.ts

@@ -1,7 +1,5 @@
-import { defineStatusExtension } from "../core/adapter-extensions.ts";
-import { ProviderDataError } from "../core/errors.ts";
-import { parseRetryAfter } from "../core/retry-after.ts";
-import type { StatusAdapter, StatusEntry, StatusSnapshot } from "../core/types.ts";
+import type { StatusAdapter, StatusEntry, StatusSnapshot } from "@hyav/pi-provider";
+import { defineStatusExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
 
 export const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
 const ACCOUNT_ID_CLAIM = "https://api.openai.com/auth";

package/status/opencode-go.ts

@@ -1,7 +1,5 @@
-import { defineStatusExtension } from "../core/adapter-extensions.ts";
-import { ProviderDataError } from "../core/errors.ts";
-import { parseRetryAfter } from "../core/retry-after.ts";
-import type { StatusAdapter, StatusEntry, StatusSnapshot } from "../core/types.ts";
+import type { StatusAdapter, StatusEntry, StatusSnapshot } from "@hyav/pi-provider";
+import { defineStatusExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
 
 export const OPENCODE_GO_USAGE_URL = "https://opencode.ai/zen/go/v1/usage";