@gtrabanco/pi-nan-provider 0.4.0 → 0.5.0

package/AGENTS.md

@@ -56,17 +56,42 @@ Every PR that changes code MUST bump `package.json` version in the same PR; CI p
 
 ## Verified API facts (do not re-derive from stale docs)
 
-- pi 0.84.4: `openAICompletionsApi` is **not** exported from the `@earendil-works/pi-ai`
-  root (the `custom-provider.md` snippet is stale). Import it from
-  `@earendil-works/pi-ai/api/openai-completions.lazy`.
-- `createProvider` and `envApiKeyAuth(name, envVars)` are on the pi-ai root.
-  `envApiKeyAuth` implements exactly: stored credential key wins → first set env
-  var → unconfigured; `login()` prompts with `{ type: "secret" }`.
+- **Extension-side pi-ai imports (v0.5.0, verified on pi-ai 0.83.0 AND 0.84.4):**
+  statically import ONLY the bare `@earendil-works/pi-ai` root from `src/`. pi's
+  extension loader maps that specifier to the compat entrypoint in every loading
+  mode (bundled CLI interception, Node-mode jiti aliases, compiled-binary
+  virtualModules), and the compat entrypoint re-exports every lazy API factory —
+  including `openAICompletionsApi`. A static SUBPATH import
+  (`@earendil-works/pi-ai/api/...`) gets the alias applied as a prefix and
+  resolves to `<compat.js>/api/...`, which does not exist: the whole extension
+  fails to load (the v0.4.x load failure). Type-only subpath imports are erased
+  before resolution and are safe; a DYNAMIC subpath `import()` is the sanctioned
+  plain-node fallback and never runs under pi because the root (compat) exports
+  the factory. Guarded by `test/extension-load.test.ts`.
+- The REAL pi-ai root (plain node/bun, outside pi) does not export
+  `openAICompletionsApi`; `createProvider` and `envApiKeyAuth(name, envVars)` are
+  on the root. `envApiKeyAuth` implements exactly: stored credential key wins →
+  first set env var → unconfigured; `login()` prompts with `{ type: "secret" }`.
+- pi awaits extension factories (`await factory(api)`) on 0.83.0 and 0.84.4
+  alike, so the extension entrypoint may be async (v0.5.0: streaming-API
+  resolution needs it).
+- pi-ai 0.83.0 runtime surface verified identical for this package's needs:
+  compat re-exports `index.js` (`createProvider`, `envApiKeyAuth`) and
+  `api/openai-completions.lazy.js`; `createProvider` options (`auth`, `models`,
+  `fetchModels(context)`, `filterModels(models, credential)`, `api`) and
+  `RefreshModelsContext.credential` match 0.84.4; `registerProvider` has both
+  the full-`Provider` and `(name, config)` overloads in 0.83's ExtensionAPI.
 - `pi.registerProvider(provider)` accepts a complete pi-ai `Provider`; pi's Models
   runtime then drives `fetchModels` refreshes (network refresh at interactive
   startup and periodically, cache-only at registration) and persists the overlay.
   A `fetchModels` rejection never blocks startup.
 - models.json overrides compose **above** registered native providers.
+- Capability values that diverge from models.dev are recorded as build-time
+  `MANUAL_OVERRIDES` (mandatory provenance note) in `scripts/manual-overrides.ts`,
+  applied by `scripts/generate-models.ts` — never hand-edited into
+  `scripts/models.generated.ts` and never invented. e.g. qwen3.8-flash
+  contextWindow 1,000,000 (maintainer-confirmed 2026-09-05; models.dev and NaN
+  docs still listed 262,144 that day).
 - Relative imports inside this package use `.ts` extensions (pi's official
   extension examples do the same; pi transpiles extension sources).
 - pi intentionally has NO built-in MCP client (docs/usage.md). MCP integration

package/README.es.md

@@ -115,10 +115,12 @@ Catálogo base (de models.dev, proveedor `nan`, obtenido 2026-09-04 — límites
 | `mimo-v2.5` | 1,048,576 | 131,072 | texto, imagen | sí |
 | `glm5.2` | 500,000 | 131,072 | texto | sí |
 | `glm5.3-flash` | 1,000,000 | 131,072 | texto, imagen | sí |
-| `qwen3.8-flash` | 262,144 | 131,072 | texto, imagen | sí |
+| `qwen3.8-flash` | 1,000,000 | 131,072 | texto, imagen | sí |
 
 Notas (grabadas por entrada en `scripts/models.generated.ts`):
 
+- La ventana de contexto de `qwen3.8-flash` está confirmada por el mantenedor en 1M (2026-09-05); models.dev y los docs de NaN aún listaban 262,144 en esa fecha. Este tipo de divergencias se registran como `MANUAL_OVERRIDES` en tiempo de build (con procedencia) en `scripts/manual-overrides.ts` — añade una ahí en vez de editar el fichero generado.
+
 - `deepseek-v4-flash` incluye entrada de imagen porque NaN sirve la variante Vision-Exp ([docs de NaN](https://nan.builders/docs/models)); models.dev la lista como solo texto.
 - `mimo-v2.5` es omnimodal (texto/imagen/audio) en NaN, pero el tipo de modelo de pi solo representa entrada texto/imagen, así que el audio se omite en `input`.
 - NaN factura por cuota de membresía, que models.dev reporta como coste cero por token — el coste mostrado por pi será $0.
@@ -131,12 +133,14 @@ Este paquete reemplaza el bloque `nan` manual de `~/.pi/agent/models.json` (el [
 
 ## Compatibilidad con versiones de pi
 
-Verificado contra pi **0.84.4** y la línea 0.85 (`registerProvider(provider)`, `registerProvider(name, config)`, `registerTool` y `modelRegistry.getApiKeyForProvider` presentes en ambas). La extensión degrada con elegancia entre versiones:
+Verificado contra pi **0.83.0**, **0.84.4** y la línea 0.85 (`registerProvider(provider)`, `registerProvider(name, config)`, `registerTool` y `modelRegistry.getApiKeyForProvider` presentes en ambas; el entrypoint compat de pi-ai reexporta la fábrica de la API openai-completions en 0.83 y 0.84 por igual). La extensión degrada con elegancia entre versiones:
 
-- **Ruta nativa (pi ≥ 0.84)**: Provider completo con auth credencial-almacenada-primero-then-env, overlay de catálogo en vivo y filtrado por tier.
-- **Fallback legacy**: si el overload nativo de Provider es rechazado, el registro cae a la forma legacy documentada `(name, config)` con el mismo catálogo generado y auth por env `$NAN_API_KEY` (la auth por credencial almacenada es una limitación del camino legacy, no un cambio silencioso).
+- **Ruta nativa**: Provider completo con auth credencial-almacenada-primero-then-env, overlay de catálogo en vivo y filtrado por tier.
+- **Fallback legacy**: si el overload nativo de Provider es rechazado (o la construcción del proveedor falla), el registro cae a la forma legacy documentada `(name, config)` con el mismo catálogo generado y auth por env `$NAN_API_KEY` (la auth por credencial almacenada es una limitación del camino legacy, no un cambio silencioso).
 - **Puentes MCP**: se omiten por completo en runtimes sin `registerTool`; los proveedores se registran igualmente.
-- `peerDependencies` es `>=0.84.4` sin límite superior.
+- **Entrada asíncrona**: pi espera las factorías de extensión en 0.83 y 0.84 por igual, así que la resolución de la API de streaming durante el registro es transparente.
+- `peerDependencies` es `>=0.83.0` sin límite superior (incluidos los forks en 0.83).
+- **Imports de pi-ai en la extensión**: solo se importa estáticamente el root `@earendil-works/pi-ai`. El loader de extensiones de pi aliasa ese especificador al entrypoint compat; los imports por subruta (p. ej. `@earendil-works/pi-ai/api/openai-completions.lazy`) reciben el alias como prefijo y no resuelven, lo que rompe la carga de toda la extensión. Protegido por `test/extension-load.test.ts`.
 
 ## helmcode
 

package/README.md

@@ -115,10 +115,11 @@ Baseline catalog (from models.dev, provider `nan`, fetched 2026-09-04 — NaN's
 | `mimo-v2.5` | 1,048,576 | 131,072 | text, image | yes |
 | `glm5.2` | 500,000 | 131,072 | text | yes |
 | `glm5.3-flash` | 1,000,000 | 131,072 | text, image | yes |
-| `qwen3.8-flash` | 262,144 | 131,072 | text, image | yes |
+| `qwen3.8-flash` | 1,000,000 | 131,072 | text, image | yes |
 
 Notes (recorded per entry in `scripts/models.generated.ts`):
 
+- `qwen3.8-flash` context window is maintainer-confirmed at 1M (2026-09-05); models.dev and NaN's docs still listed 262,144 at that date. Divergences like this are recorded as build-time `MANUAL_OVERRIDES` (with provenance) in `scripts/manual-overrides.ts` — apply one instead of editing the generated file.
 - `deepseek-v4-flash` includes image input because NaN serves the Vision-Exp variant ([NaN docs](https://nan.builders/docs/models)); models.dev lists text only.
 - `mimo-v2.5` is omnimodal (text/image/audio) on NaN, but pi's model type only represents text/image input, so audio is dropped from `input`.
 - NaN bills via membership quota, which models.dev reports as zero per-token cost — pi's cost display will read $0.
@@ -131,12 +132,14 @@ This package replaces the hand-written `nan` block in `~/.pi/agent/models.json`
 
 ## pi version compatibility
 
-Verified against pi **0.84.4** and the 0.85 line (`registerProvider(provider)`, `registerProvider(name, config)`, `registerTool`, and `modelRegistry.getApiKeyForProvider` all present in both). The extension degrades gracefully across versions:
+Verified against pi **0.83.0**, **0.84.4**, and the 0.85 line (`registerProvider(provider)`, `registerProvider(name, config)`, `registerTool`, and `modelRegistry.getApiKeyForProvider` all present in both; pi-ai's compat entrypoint re-exports the openai-completions API factory on 0.83 and 0.84 alike). The extension degrades gracefully across versions:
 
-- **Native path (pi ≥ 0.84)**: full Provider with stored-credential-then-env auth, live catalog overlay, and tier filtering.
-- **Legacy fallback**: if the native Provider overload is rejected, registration falls back to the documented legacy `(name, config)` form with the same generated catalog and `$NAN_API_KEY` env auth (stored-credential auth is a limitation of the legacy path, not a silent behavior change).
+- **Native path**: full Provider with stored-credential-then-env auth, live catalog overlay, and tier filtering.
+- **Legacy fallback**: if the native Provider overload is rejected (or provider construction fails), registration falls back to the documented legacy `(name, config)` form with the same generated catalog and `$NAN_API_KEY` env auth (stored-credential auth is a limitation of the legacy path, not a silent behavior change).
 - **MCP bridges**: skipped entirely on runtimes without `registerTool`; providers still register.
-- `peerDependencies` is `>=0.84.4` with no upper bound.
+- **Async entrypoint**: pi awaits extension factories on 0.83 and 0.84 alike, so the streaming-API resolution at registration is transparent.
+- `peerDependencies` is `>=0.83.0` with no upper bound (0.83 forks included).
+- **Extension-side pi-ai imports**: only the bare `@earendil-works/pi-ai` root is imported statically. pi's extension loader aliases that specifier to the compat entrypoint; subpath imports (e.g. `@earendil-works/pi-ai/api/openai-completions.lazy`) get the alias applied as a prefix and fail to resolve, which is a whole-extension load failure. Guarded by `test/extension-load.test.ts`.
 
 ## helmcode
 

package/package.json

@@ -1,18 +1,20 @@
 {
 	"name": "@gtrabanco/pi-nan-provider",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "NaN Builders (api.nan.builders) model provider for pi - OpenAI-compatible registration with a models.dev-generated fallback, tier-aware live catalog, and MCP bridges (official web search + optional community media server)",
 	"keywords": [
 		"pi",
 		"pi-package",
 		"pi-extension",
-		"pi-coding-agent",
+		"provider",
 		"ai",
 		"ai-provider",
+		"llm",
 		"nan",
 		"nan-builders",
+		"api-nan-builders",
 		"openai-compatible",
-		"litellm"
+		"ai-model"
 	],
 	"type": "module",
 	"main": "./src/index.ts",
@@ -38,14 +40,14 @@
 		"typecheck": "bunx tsc --noEmit"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-ai": ">=0.84.4 <1",
-		"@earendil-works/pi-coding-agent": ">=0.84.4 <1"
+		"@earendil-works/pi-ai": ">=0.83.0 <1",
+		"@earendil-works/pi-coding-agent": ">=0.83.0 <1"
 	},
 	"devDependencies": {
 		"@earendil-works/pi-ai": "0.84.4",
 		"@earendil-works/pi-coding-agent": "0.84.4",
-		"@types/bun": "latest",
-		"typescript": "^5.9.2"
+		"@types/bun": "1.4",
+		"typescript": "7"
 	},
 	"license": "MIT",
 	"repository": {

package/scripts/generate-models.ts

@@ -21,6 +21,7 @@
  */
 
 import type { GeneratedModelEntry } from "../src/fetch-models.ts";
+import { MANUAL_OVERRIDES } from "./manual-overrides.ts";
 
 const MODELS_DEV_API_URL = "https://models.dev/api.json";
 const SOURCE_PROVIDER_ID = "nan";
@@ -33,22 +34,10 @@ const REQUIRED_MODEL_IDS = ["qwen3.6", "gemma4", "deepseek-v4-flash", "mimo-v2.5
 const PI_SUPPORTED_INPUT = new Set(["text", "image"]);
 
 /**
- * Manual corrections over models.dev, each with its confirmation source.
- * Applied only to fields NaN's own documentation contradicts or pi cannot
- * represent; the note is emitted onto the generated entry.
- */
-const MANUAL_OVERRIDES: Record<string, { input?: ("text" | "image")[]; note: string }> = {
-	"deepseek-v4-flash": {
-		input: ["text", "image"],
-		note: "input includes image: NaN serves the Vision-Exp variant (confirmed at https://nan.builders/docs/models, 'takes images as input'); models.dev provider nan lists text only.",
-	},
-};
-
-/**
- * Per-model provenance notes sourced from NaN's own documentation (manual —
- * models.dev has no structured tier/quota data), each stating its source.
- * Empty today: no model in the models.dev `nan` provider is tier-gated
- * (the premium-tier GLM 5.3 is not listed there; only glm5.3-flash is).
+ * Manual corrections over models.dev live in scripts/manual-overrides.ts
+ * (shared with test/generated-catalog.test.ts, which pins that every
+ * override lands on the generated entry with its provenance note).
+ * Capabilities diverging from models.dev are recorded there, never here.
  */
 const MANUAL_NOTES: Record<string, string> = {};
 
@@ -136,20 +125,25 @@ function convertModel(modelId: string, m: ModelsDevModel): GeneratedModel | { sk
 	const override = MANUAL_OVERRIDES[modelId];
 	const input = override?.input ?? normalizeInput(m.modalities?.input, modelId);
 
+	if (override) {
+		const overridden = Object.keys(override).filter((key) => key !== "note");
+		console.log(`generate-models: manual override for "${modelId}" (${overridden.join(", ")})`);
+	}
+
 	return {
 		entry: {
 			id: modelId,
-			name: m.name ?? modelId,
-			reasoning: m.reasoning === true,
+			name: override?.name ?? m.name ?? modelId,
+			reasoning: override?.reasoning ?? m.reasoning === true,
 			input,
-			cost: {
+			cost: override?.cost ?? {
 				input: m.cost?.input ?? 0,
 				output: m.cost?.output ?? 0,
 				cacheRead: m.cost?.cache_read ?? 0,
 				cacheWrite: m.cost?.cache_write ?? 0,
 			},
-			contextWindow,
-			maxTokens,
+			contextWindow: override?.contextWindow ?? contextWindow,
+			maxTokens: override?.maxTokens ?? maxTokens,
 			compat: { ...NAN_COMPAT },
 			notes: [
 				NAN_COMPAT_NOTE,
@@ -158,6 +152,8 @@ function convertModel(modelId: string, m: ModelsDevModel): GeneratedModel | { sk
 			],
 			// Preserve every property models.dev documents for this model verbatim
 			// (tier, quotas, release dates, reasoning options, attachments...).
+			// Extras keep the UN-overridden models.dev data: they are the provenance
+			// record of what models.dev says, not a capability claim.
 			extras: m as unknown as Record<string, unknown>,
 		},
 	};

package/scripts/manual-overrides.ts

@@ -0,0 +1,47 @@
+/**
+ * MANUAL_OVERRIDES — build-time corrections applied over the models.dev data
+ * by scripts/generate-models.ts before emitting scripts/models.generated.ts.
+ *
+ * models.dev lags behind gateway-side capability changes (context windows,
+ * max output tokens, modalities). When a served value diverges from
+ * models.dev, record it here instead of hand-editing the generated file.
+ *
+ * Provenance rules (mirrors AGENTS.md):
+ * - `note` is REQUIRED and must state where the value was confirmed
+ *   (URL and/or who confirmed it, plus the date) — and, when the override
+ *   contradicts a public source, that source and its value, so the entry
+ *   can be re-verified later.
+ * - Never guess a number. If no confirmation source exists, leave the
+ *   models.dev value in place.
+ *
+ * Fields override the models.dev-derived entry one-for-one:
+ * name, reasoning, input, cost, contextWindow, maxTokens.
+ */
+
+export interface ManualModelOverride {
+	/** Display name override. */
+	name?: string;
+	/** Reasoning support override. */
+	reasoning?: boolean;
+	/** pi-representable input modalities override. */
+	input?: ("text" | "image")[];
+	/** Per-token cost override (USD/Mtok; NaN is membership-quota based, so 0 unless confirmed otherwise). */
+	cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+	/** Context window override (tokens). */
+	contextWindow?: number;
+	/** Max output tokens override. */
+	maxTokens?: number;
+	/** Required provenance note; emitted verbatim onto the generated entry. */
+	note: string;
+}
+
+export const MANUAL_OVERRIDES: Record<string, ManualModelOverride> = {
+	"deepseek-v4-flash": {
+		input: ["text", "image"],
+		note: "input includes image: NaN serves the Vision-Exp variant (confirmed at https://nan.builders/docs/models, 'takes images as input'); models.dev provider nan lists text only.",
+	},
+	"qwen3.8-flash": {
+		contextWindow: 1_000_000,
+		note: "contextWindow 1,000,000: maintainer-confirmed against api.nan.builders (2026-09-05); both models.dev and https://nan.builders/docs/models still listed 262,144 ('262K token context, the model's native window') as of 2026-09-05 — re-verify against the gateway/docs when they update.",
+	},
+};

package/scripts/models.generated.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by scripts/generate-models.ts
 // Do not edit manually — run `bun run generate-models` to update.
 //
-// Source: https://models.dev/api.json (provider "nan"), fetched 2026-09-04T19:41:30.417Z
+// Source: https://models.dev/api.json (provider "nan"), fetched 2026-09-05T11:12:14.773Z
 // Provenance: every contextWindow/maxTokens/input/cost value traces to
 // models.dev or to the per-entry notes below. Nothing is invented; entries
 // models.dev documents incompletely are omitted and flagged instead.
@@ -382,7 +382,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"cacheRead": 0,
 			"cacheWrite": 0
 		},
-		"contextWindow": 262144,
+		"contextWindow": 1000000,
 		"maxTokens": 131072,
 		"compat": {
 			"supportsDeveloperRole": false,
@@ -391,7 +391,8 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"maxTokensField": "max_tokens"
 		},
 		"notes": [
-			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, supportsUsageInStreaming true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested."
+			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, supportsUsageInStreaming true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested.",
+			"contextWindow 1,000,000: maintainer-confirmed against api.nan.builders (2026-09-05); both models.dev and https://nan.builders/docs/models still listed 262,144 ('262K token context, the model's native window') as of 2026-09-05 — re-verify against the gateway/docs when they update."
 		],
 		"extras": {
 			"id": "qwen3.8-flash",
@@ -430,11 +431,12 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 export const GENERATED_CATALOG_META = {
 	source: "https://models.dev/api.json",
 	modelsDevProvider: "nan",
-	fetchedAt: "2026-09-04T19:41:30.417Z",
+	fetchedAt: "2026-09-05T11:12:14.773Z",
 	modelCount: 7,
 	models: ["deepseek-v4-flash","gemma4","glm5.2","glm5.3-flash","mimo-v2.5","qwen3.6","qwen3.8-flash"],
 	notes: [
 	"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, supportsUsageInStreaming true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested.",
-	"input includes image: NaN serves the Vision-Exp variant (confirmed at https://nan.builders/docs/models, 'takes images as input'); models.dev provider nan lists text only."
+	"input includes image: NaN serves the Vision-Exp variant (confirmed at https://nan.builders/docs/models, 'takes images as input'); models.dev provider nan lists text only.",
+	"contextWindow 1,000,000: maintainer-confirmed against api.nan.builders (2026-09-05); both models.dev and https://nan.builders/docs/models still listed 262,144 ('262K token context, the model's native window') as of 2026-09-05 — re-verify against the gateway/docs when they update."
 ],
 } as const;

package/src/index.ts

@@ -11,16 +11,22 @@
  *     without the native Provider overload, registration falls back to the
  *     legacy (name, config) form with the same baseline catalog.
  *
+ *     The entrypoint is async: pi awaits extension factories (0.83 and
+ *     0.84 alike), and the openai-completions streaming implementation is
+ *     resolved dynamically — see provider-factory.ts for why.
+ *
  *  2. MCP tools over pi's registerTool (pi intentionally has no MCP client):
  *     - `nan_web_search` via NaN's official remote MCP server
  *       (https://api.nan.builders/mcp) — on by default, NAN_MCP_TOOLS=0 to
  *       disable.
  *     - Media tools bridging the optional community `nan-mcp-server`
- *       (stdio, spawned per call) — off by default, NAN_MEDIA_MCP=1 to
- *       enable, so nothing runs unless audio/image/transcription is invoked.
+ *       (stdio, spawned per call) — on by default, NAN_MEDIA_MCP=0 to
+ *       disable. The server spawns per tool call, so nothing runs unless
+ *       audio/image/transcription is actually invoked.
  */
 
 import type { ExtensionAPI, ProviderConfig } from "@earendil-works/pi-coding-agent";
+import type { Provider } from "@earendil-works/pi-ai";
 import { registerNanMcpCommand } from "./commands.ts";
 import { baselineModels } from "./fetch-models.ts";
 import { createNanWebSearchTool, webSearchBridgeEnabled, NAN_API_KEY_ENV } from "./mcp/nan-search.ts";
@@ -34,14 +40,18 @@ import { PROVIDERS } from "./providers.ts";
  * env-var auth. The fallback loses stored-credential auth (env only) — a
  * documented limitation of the legacy path, never a silent auth invention.
  */
-function registerProviderCompat(pi: ExtensionAPI, config: OpenAICompatibleProviderConfig): void {
-	const native = createNanCompatibleProvider(config);
+async function registerProviderCompat(
+	pi: ExtensionAPI,
+	config: OpenAICompatibleProviderConfig,
+): Promise<void> {
+	let native: Provider<"openai-completions"> | undefined;
 	try {
+		native = await createNanCompatibleProvider(config);
 		pi.registerProvider(native);
 		return;
 	} catch (error) {
 		console.warn(
-			`[pi-nan-provider] native provider registration rejected (${error instanceof Error ? error.message : String(error)}); ` +
+			`[pi-nan-provider] native provider path failed (${error instanceof Error ? error.message : String(error)}); ` +
 				"falling back to legacy config form (env-var auth only).",
 		);
 	}
@@ -98,9 +108,9 @@ function registerMcpToolsCompat(pi: ExtensionAPI): void {
 	}
 }
 
-export default function nanProviderExtension(pi: ExtensionAPI): void {
+export default async function nanProviderExtension(pi: ExtensionAPI): Promise<void> {
 	for (const config of PROVIDERS) {
-		registerProviderCompat(pi, config);
+		await registerProviderCompat(pi, config);
 	}
 	registerMcpToolsCompat(pi);
 }

package/src/mcp/nan-media.ts

@@ -4,8 +4,9 @@
  * exposes NaN's media tools: image generation/editing (flux-2-klein), TTS
  * (kokoro), STT (whisper), plus voice listing.
  *
- * Opt-in and fully lazy:
- * - OFF by default. Enable with NAN_MEDIA_MCP=1.
+ * Both MCP bridges are enabled by default and fully lazy:
+ * - ON by default. NAN_MEDIA_MCP=0 (or false/off) disables it for one
+ *   session; `/nan-mcp disable nan-mcp-server` persists the toggle.
  * - The server process is spawned per tool call and terminated right after —
  *   zero startup cost, nothing runs unless audio/image/transcription is
  *   actually invoked.

package/src/provider-factory.ts

@@ -6,18 +6,26 @@
  * catalog data, never a parallel implementation.
  *
  * The resulting provider follows pi-ai's built-in provider shape (see
- * `deepseekProvider()` in pi-ai): `createProvider` + `envApiKeyAuth` +
- * `openAICompletionsApi`, with a `fetchModels` overlay that merges the live
- * /models listing with the generated fallback catalog.
+ * `deepseekProvider()` in pi-ai): `createProvider` + `envApiKeyAuth` + the
+ * openai-completions streaming API, with a `fetchModels` overlay that merges
+ * the live /models listing with the generated fallback catalog.
+ *
+ * pi-ai import rule (see test/extension-load.test.ts): extensions must
+ * statically import ONLY the bare `@earendil-works/pi-ai` root. pi's
+ * extension loader maps that specifier to the compat entrypoint on every
+ * supported runtime (bundled CLI, Node-mode aliases, compiled-binary
+ * virtualModules; pi 0.83 and 0.84 alike), and compat re-exports every lazy
+ * API factory. Subpath specifiers (`@earendil-works/pi-ai/api/...`) get the
+ * alias applied as a prefix and resolve to `<compat.js>/api/...`, which does
+ * not exist — the extension then fails to load entirely.
  */
 
-import {
-	createProvider,
-	envApiKeyAuth,
-	type Provider,
-	type RefreshModelsContext,
+import * as piAi from "@earendil-works/pi-ai";
+import type {
+	Provider,
+	ProviderStreams,
+	RefreshModelsContext,
 } from "@earendil-works/pi-ai";
-import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
 import {
 	baselineModels,
 	DEFAULT_MODELS_TIMEOUT_MS,
@@ -43,6 +51,35 @@ export interface NanCompatibleProviderOptions {
 	fetchImpl?: typeof fetch;
 }
 
+/**
+ * Resolve the openai-completions streaming implementation at runtime.
+ *
+ * Under pi, the bare-root namespace is pi's compat entrypoint, which
+ * re-exports `openAICompletionsApi` on both pi-ai 0.83 and 0.84 — so the
+ * first branch always wins and no pi-ai subpath is ever resolved there.
+ * Outside pi (plain node/bun: tests and direct consumers) the real root
+ * does not export the lazy factory; the dynamic subpath import below uses
+ * the package's normal `./api/*` export. It is never reached under pi, so
+ * the alias-prefix pitfall cannot bite at runtime.
+ */
+type OpenAICompletionsApiFactory = () => ProviderStreams;
+
+let cachedApiFactory: OpenAICompletionsApiFactory | undefined;
+
+export async function resolveOpenAICompletionsApi(): Promise<OpenAICompletionsApiFactory> {
+	if (cachedApiFactory) return cachedApiFactory;
+	const fromRoot = (
+		piAi as unknown as Partial<Record<"openAICompletionsApi", OpenAICompletionsApiFactory>>
+	).openAICompletionsApi;
+	if (typeof fromRoot === "function") {
+		cachedApiFactory = fromRoot;
+		return cachedApiFactory;
+	}
+	cachedApiFactory = (await import("@earendil-works/pi-ai/api/openai-completions.lazy"))
+		.openAICompletionsApi;
+	return cachedApiFactory;
+}
+
 /**
  * Build a complete pi-ai Provider for an OpenAI-compatible endpoint:
  *
@@ -55,12 +92,14 @@ export interface NanCompatibleProviderOptions {
  * - fetchModels: live `/models` IDs × generated capability data; falls back
  *   to the baseline when the endpoint is unreachable. pi's Models runtime
  *   drives refreshes (startup/periodic) and persists the overlay.
- * - api: `openAICompletionsApi()` (lazy-loaded streaming implementation).
+ * - api: the openai-completions streaming implementation (see
+ *   `resolveOpenAICompletionsApi` for why this is resolved dynamically).
  */
-export function createNanCompatibleProvider(
+export async function createNanCompatibleProvider(
 	config: OpenAICompatibleProviderConfig,
 	options: NanCompatibleProviderOptions = {},
-): Provider<"openai-completions"> {
+): Promise<Provider<"openai-completions">> {
+	const apiFactory = await resolveOpenAICompletionsApi();
 	const source: CatalogSource = { providerId: config.id, baseUrl: config.baseUrl };
 
 	// Last successful live /models result, shared between fetchModels (writes)
@@ -70,11 +109,11 @@ export function createNanCompatibleProvider(
 	// `available` (e.g. premium-tier models you are not subscribed to).
 	let liveIds: Set<string> | undefined;
 
-	return createProvider({
+	return piAi.createProvider({
 		id: config.id,
 		name: config.name,
 		baseUrl: config.baseUrl,
-		auth: { apiKey: envApiKeyAuth(`${config.name} API key`, config.envVars) },
+		auth: { apiKey: piAi.envApiKeyAuth(`${config.name} API key`, config.envVars) },
 		models: baselineModels(source),
 		fetchModels: async (context: RefreshModelsContext) => {
 			const credential = context.credential;
@@ -91,6 +130,6 @@ export function createNanCompatibleProvider(
 			const current = liveIds;
 			return current ? models.filter((model) => current.has(model.id)) : models;
 		},
-		api: openAICompletionsApi(),
+		api: apiFactory(),
 	});
 }