@gtrabanco/pi-nan-provider 0.6.8 → 0.6.10

package/AGENTS.md

@@ -77,18 +77,29 @@ 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)
 
-- **Extension-side pi-ai imports (v0.5.0, verified on pi-ai 0.83.0 AND 0.84.4):**
+- **Extension-side pi-ai imports + streaming-API instance binding (v0.6.10; verified on pi-ai 0.83.0–0.84.4 and pi 0.87.0):**
   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`.
+  extension loader maps that specifier to the compat entrypoint on the bundled
+  CLI, Node-mode jiti aliases and compiled-binary virtualModules, and compat
+  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.
+  **Exception (issue #8):** on pi-web's sessiond-on-Bun loader (pi-web
+  1.202609.0 / pi 0.87.0 / Bun) the bare root is NOT aliased to `/compat`
+  (observed namespace = core, `import.meta.resolve` = core), and a bare SUBPATH
+  specifier resolved to a stale hoisted `@earendil-works/pi-ai@0.85.1` under
+  `~/.pi/agent/npm/node_modules`; its `estimateMessageTokens` lacks the `system`
+  branch and crashes pi 0.87's string-content `system` transcript with
+  `block.name.length`. `src/pi-ai-loader.ts` therefore binds the streaming
+  factory to the same package instance as the bare-root import: use the root
+  export when present, else derive a FILE URL from
+  `import.meta.resolve("@earendil-works/pi-ai")`
+  (`api/openai-completions.lazy.js`, then `compat.js`). No bare pi-ai subpath
+  specifier is imported anywhere in `src/` (static or dynamic); failure is loud
+  (`PiAiStreamingApiResolutionError`). Guarded by `test/extension-load.test.ts`
+  and `test/issue-8-pi-ai-instance.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 →
@@ -136,14 +147,21 @@ Every PR that changes code MUST bump `package.json` version in the same PR; CI p
   `supportsFinishReason: true` so pi-ai raises the retryable
   `Stream ended without finish_reason` (pi-ai's `RETRYABLE_PROVIDER_ERROR_PATTERN`
   matches `"ended without"`, so the turn is retried) instead of silently
-  synthesizing `stop`/`toolUse`. `supportsUsageInStreaming` stays `false` by
-  default (NaN's published schema does not document `stream_options`), but the
-  sanitizer gates its `stream_options` removal on the model's effective
-  `compat.supportsUsageInStreaming`, so a confirmed per-model `models.json`
-  override now yields real usage instead of being silently undone
-  (`test/issue-4-token-usage.test.ts`; issues #2, #4). Regression tests:
-  `test/issue-2-truncated-stream.test.ts`, `test/issue-4-token-usage.test.ts`;
-  issues #2 and #4.
+  synthesizing `stop`/`toolUse`. `supportsUsageInStreaming` is `true` for chat
+  models (issue #7): NaN's published schema does not document `stream_options`,
+  but the live gateway honors `stream_options.include_usage` — measured
+  2026-09-16 on `deepseek-v4-flash`, `glm5.3-flash`, `qwen3.6`, `mimo-v2.5` and
+  `gemma4` (0 usage chunks without the flag, exactly 1 with it, carrying
+  prompt/completion/reasoning/cached counts; a real pi session then recorded
+  real tokens where it recorded zeros). The sanitizer gates its
+  `stream_options` removal on the model's effective
+  `compat.supportsUsageInStreaming`, so the stock catalog reports real usage and
+  a per-model `models.json` override of `false` restores the strict payload
+  (`test/issue-4-token-usage.test.ts`, `test/issue-7-streaming-usage-default.test.ts`;
+  issues #2, #4, #7). Regression tests:
+  `test/issue-2-truncated-stream.test.ts`, `test/issue-4-token-usage.test.ts`,
+  `test/issue-7-streaming-usage-default.test.ts`;
+  issues #2, #4 and #7.
 - A NaN request that still exceeds the destination model's context window (the
   cross-model thinking guard is disabled with `NAN_THINKING_GUARD=0`, the
   inflation is not a `thinking` block, or the window is smaller) gets NaN's

package/README.es.md

@@ -71,14 +71,14 @@ Puedes sobrescribir el `compat` de cualquier modelo en `~/.pi/agent/models.json`
 
 > Poner `supportsFinishReason: false` restaura el antiguo stall silencioso — no recomendado.
 
-**Uso de tokens en streaming:** `supportsUsageInStreaming` es `false` por defecto porque el esquema publicado de NaN no documenta `stream_options`; sin él, el usage aparece a cero. Si has confirmado que tu modelo devuelve el chunk de usage en streaming, activalo por modelo — el sanitizer de peticiones entonces reenvía `stream_options: { "include_usage": true }` y pi muestra los tokens reales en lugar de ceros:
+**Uso de tokens en streaming:** `supportsUsageInStreaming` es `true` por defecto. El esquema publicado de NaN no documenta `stream_options`, pero el gateway real lo acepta y lo aplica — medido el 2026-09-16 ([#7](https://github.com/gtrabanco/pi-nan-provider/issues/7)): dos llamadas de streaming idénticas por modelo, 0 chunks de usage sin el flag y exactamente 1 con él, en `deepseek-v4-flash`, `glm5.3-flash`, `qwen3.6`, `mimo-v2.5` y `gemma4`. Por eso pi muestra tokens reales de entrada/salida/reasoning/caché en lugar de ceros. Si un modelo resulta no devolver el usage en streaming, desactívalo por modelo — el sanitizer entonces elimina `stream_options` y el payload vuelve a ser estricto:
 
 ```json
 {
   "providers": {
     "nan": {
       "modelOverrides": {
-        "qwen3.6": { "compat": { "supportsUsageInStreaming": true } }
+        "some-model": { "compat": { "supportsUsageInStreaming": false } }
       }
     }
   }
@@ -154,6 +154,78 @@ bun run check-nan-mcp-server --issue    # crea/refresca el issue
 
 ---
 
+## 📊 Uso de Cuotas: `/nan-usage`
+
+Muestra tu uso de tokens de NaN por modelo, los límites mensuales y el tiempo hasta el reinicio del ciclo de facturación.
+
+### Cómo funciona
+
+`/nan-usage` lee el token de sesión desde `~/.config/nan/session.json` — el mismo archivo que usa la [CLI de NaN](https://github.com/helmcode/nan-cli). Si el archivo existe y contiene una sesión válida, el comando obtiene datos de uso reales del dashboard de NaN. Si no, muestra los límites de cuota estáticos de la documentación.
+
+### Configuración
+
+1. **Instala la CLI de NaN**:
+   ```bash
+   curl -fsSL https://nan.builders/install | sh
+   ```
+2. **Inicia sesión**:
+   ```bash
+   nan auth login
+   ```
+   Te envía un enlace de inicio de sesión por email. Pega el enlace en la terminal.
+3. **Usa en pi**:
+   ```
+   /nan-usage
+   ```
+
+> [!TIP]
+> El token de sesión se comparte automáticamente — no necesitas variables de entorno ni configuración extra. Si la sesión expira, ejecuta `nan auth login` de nuevo.
+
+### Lo que ves
+
+**Con sesión válida** (uso real):
+```
+📊 NaN Quota Status
+
+⏱️  Next billing reset: 2026-10-01 UTC (8d 14h 32m 15s)
+
+Models with monthly caps:
+
+DeepSeek V4 Flash:
+  [████████░░░░░░░░░░░░] 40.2%
+  Used: 1.2B / 3.0B (1.8B remaining)
+
+MiMo V2.5:
+  [██░░░░░░░░░░░░░░░░░░] 12.5%
+  Used: 125.0M / 1.0B (875.0M remaining)
+
+Uncapped models:
+
+Qwen 3.6: 890.5K used
+Gemma 4: 234.1K used
+```
+
+**Sin sesión** (solo límites estáticos):
+```
+📊 NaN Quota Status (static limits)
+
+⏱️  Next billing reset: 2026-10-01 UTC (8d 14h 32m 15s)
+
+Model                        Monthly Cap
+─────────────────────────────────────────────────
+DeepSeek V4 Flash            3.0B
+MiMo V2.5                    1.0B
+Qwen 3.6                     uncapped
+Gemma 4                      uncapped
+Qwen 3.8 Flash               500.0M
+GLM 5.3 Flash                2.0B
+GLM 5.3 👑                   3.0B (rolling 400.0M/4h)
+
+💡 Run `nan auth login` to see real usage data.
+```
+
+---
+
 ## 📊 Modelos
 
 Catálogo base (verificado contra [docs de NaN](https://nan.builders/docs/models) y [OpenAPI](https://nan.builders/openapi.json)).

package/README.md

@@ -71,14 +71,14 @@ You can override any model's `compat` per-model in `~/.pi/agent/models.json` (pi
 
 > Setting `supportsFinishReason: false` restores the old silent-stall behavior — not recommended.
 
-**Streaming token usage:** `supportsUsageInStreaming` is `false` by default because NaN's published schema does not document `stream_options`; without it usage reads as zero. If you have confirmed that your model returns a streaming usage chunk, opt in per model — the request sanitizer then forwards `stream_options: { "include_usage": true }` and pi reports real token counts instead of zeros:
+**Streaming token usage:** `supportsUsageInStreaming` is `true` by default. NaN's published schema does not document `stream_options`, but the live gateway honors it — measured 2026-09-16 ([#7](https://github.com/gtrabanco/pi-nan-provider/issues/7)): two identical streaming calls per model, 0 usage chunks without the flag and exactly 1 with it, on `deepseek-v4-flash`, `glm5.3-flash`, `qwen3.6`, `mimo-v2.5` and `gemma4`. pi therefore reports real input/output/reasoning/cache token counts instead of zeros. If a model turns out not to report streaming usage, opt out per model — the request sanitizer then strips `stream_options` and the payload stays strict:
 
 ```json
 {
   "providers": {
     "nan": {
       "modelOverrides": {
-        "qwen3.6": { "compat": { "supportsUsageInStreaming": true } }
+        "some-model": { "compat": { "supportsUsageInStreaming": false } }
       }
     }
   }
@@ -154,6 +154,78 @@ bun run check-nan-mcp-server --issue    # create/refresh the issue
 
 ---
 
+## 📊 Quota Usage: `/nan-usage`
+
+Shows your NaN token usage per model, monthly limits, and time until the billing cycle resets.
+
+### How it works
+
+`/nan-usage` reads the session token from `~/.config/nan/session.json` — the same file the [NaN CLI](https://github.com/helmcode/nan-cli) uses. If the file exists and contains a valid session, the command fetches real usage data from NaN's dashboard. Otherwise, it shows static quota limits from the docs.
+
+### Setup
+
+1. **Install the NaN CLI**:
+   ```bash
+   curl -fsSL https://nan.builders/install | sh
+   ```
+2. **Log in**:
+   ```bash
+   nan auth login
+   ```
+   This sends a sign-in link to your email. Paste the link back into the terminal.
+3. **Use in pi**:
+   ```
+   /nan-usage
+   ```
+
+> [!TIP]
+> The session token is shared automatically — no env vars or extra config needed. If the session expires, run `nan auth login` again.
+
+### What you see
+
+**With a valid session** (real usage):
+```
+📊 NaN Quota Status
+
+⏱️  Next billing reset: 2026-10-01 UTC (8d 14h 32m 15s)
+
+Models with monthly caps:
+
+DeepSeek V4 Flash:
+  [████████░░░░░░░░░░░░] 40.2%
+  Used: 1.2B / 3.0B (1.8B remaining)
+
+MiMo V2.5:
+  [██░░░░░░░░░░░░░░░░░░] 12.5%
+  Used: 125.0M / 1.0B (875.0M remaining)
+
+Uncapped models:
+
+Qwen 3.6: 890.5K used
+Gemma 4: 234.1K used
+```
+
+**Without a session** (static limits only):
+```
+📊 NaN Quota Status (static limits)
+
+⏱️  Next billing reset: 2026-10-01 UTC (8d 14h 32m 15s)
+
+Model                        Monthly Cap
+─────────────────────────────────────────────────
+DeepSeek V4 Flash            3.0B
+MiMo V2.5                    1.0B
+Qwen 3.6                     uncapped
+Gemma 4                      uncapped
+Qwen 3.8 Flash               500.0M
+GLM 5.3 Flash                2.0B
+GLM 5.3 👑                   3.0B (rolling 400.0M/4h)
+
+💡 Run `nan auth login` to see real usage data.
+```
+
+---
+
 ## 📊 Models
 
 Baseline catalog (verified against [NaN docs](https://nan.builders/docs/models) and [OpenAPI](https://nan.builders/openapi.json)).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gtrabanco/pi-nan-provider",
-	"version": "0.6.8",
+	"version": "0.6.10",
 	"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",

package/scripts/generate-models.ts

@@ -83,14 +83,16 @@ const LIVE_ONLY_MODEL_IDS: Record<string, string> = {
 const NAN_COMPAT = {
 	supportsDeveloperRole: false,
 	supportsReasoningEffort: true,
-	// pi-ai only sends `stream_options: { include_usage: true }` when this is
-	// not false. NaN's published schema does not document `stream_options`, so
-	// the conservative default is false: the sanitizer strips it and usage
-	// stays zero. A user who confirms their gateway reports streaming usage
-	// can opt in per model with a models.json compat override
-	// (`supportsUsageInStreaming: true`); the sanitizer then forwards
-	// `stream_options` instead of deleting it (issue #4, 2026-09-13).
-	supportsUsageInStreaming: false,
+	// NaN's published schema is silent about `stream_options`, but the live
+	// gateway honors it (issue #7, measured 2026-09-16 on five chat models:
+	// 0 usage chunks without the flag, exactly 1 with it). pi-ai only sends
+	// `stream_options: { include_usage: true }` when this is not false, and the
+	// sanitizer forwards it when the model declares true, so chat models opt in
+	// by default and pi reports real token counts instead of zeros (issue #4).
+	// A model that does not report streaming usage can still opt out per model
+	// with a models.json compat override (`supportsUsageInStreaming: false`);
+	// the sanitizer then strips `stream_options` and the payload stays strict.
+	supportsUsageInStreaming: true,
 	// The NaN/LiteLLM gateway intermittently closes SSE streams before emitting
 	// `finish_reason`. With true, pi-ai raises "Stream ended without
 	// finish_reason", which its retryable-provider pattern ("ended without")
@@ -102,7 +104,7 @@ const NAN_COMPAT = {
 };
 
 const NAN_COMPAT_NOTE =
-	"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming false (2026-09-13): pi-ai only sends stream_options when this is not false, and NaN's published schema does not document it, so the conservative default stays false (sanitizer removes stream_options, usage reads zero). A user who has confirmed that their model returns a streaming usage chunk can opt in per model with a models.json compat override (supportsUsageInStreaming: true); the sanitizer then forwards stream_options instead of deleting it (issue #4).";
+	"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming true (2026-09-16, issue #7): NaN's published schema is silent about stream_options, but the live gateway honors it — two identical streaming calls per model, differing only in stream_options: { include_usage: true }, returned 0 usage chunks without it and exactly 1 with it (prompt/completion/reasoning/cached token counts) on deepseek-v4-flash, glm5.3-flash, qwen3.6, mimo-v2.5 and gemma4, and a real pi session then recorded token counts where it recorded zeros. pi-ai only sends stream_options when this is not false, and the sanitizer forwards it when the model declares true, so chat models opt in by default and usage is reported (issue #4). A model that does not report streaming usage can still opt out per model with a models.json compat override (supportsUsageInStreaming: false); the sanitizer then strips stream_options and the payload stays strict.";
 
 interface ModelsDevModel {
 	id?: string;

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-14T20:40:55.922Z
+// Source: https://models.dev/api.json (provider "nan"), fetched 2026-09-21T23:54:45.052Z
 // 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.
@@ -31,12 +31,12 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 		"compat": {
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
-			"supportsUsageInStreaming": false,
+			"supportsUsageInStreaming": true,
 			"supportsFinishReason": true,
 			"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, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming false (2026-09-13): pi-ai only sends stream_options when this is not false, and NaN's published schema does not document it, so the conservative default stays false (sanitizer removes stream_options, usage reads zero). A user who has confirmed that their model returns a streaming usage chunk can opt in per model with a models.json compat override (supportsUsageInStreaming: true); the sanitizer then forwards stream_options instead of deleting it (issue #4).",
+			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming true (2026-09-16, issue #7): NaN's published schema is silent about stream_options, but the live gateway honors it — two identical streaming calls per model, differing only in stream_options: { include_usage: true }, returned 0 usage chunks without it and exactly 1 with it (prompt/completion/reasoning/cached token counts) on deepseek-v4-flash, glm5.3-flash, qwen3.6, mimo-v2.5 and gemma4, and a real pi session then recorded token counts where it recorded zeros. pi-ai only sends stream_options when this is not false, and the sanitizer forwards it when the model declares true, so chat models opt in by default and usage is reported (issue #4). A model that does not report streaming usage can still opt out per model with a models.json compat override (supportsUsageInStreaming: false); the sanitizer then strips stream_options and the payload stays strict.",
 			"input includes image: NaN serves the Vision-Exp variant ('takes images as input', https://nan.builders/docs/models; the image_url content-parts in https://nan.builders/openapi.json list deepseek-v4-flash among the vision models). models.dev provider nan also lists text+image now (DeepSeek V4.1 Flash entry, checked 2026-09-13; its 2026-09-07 snapshot listed text only), so this override is kept as a pin for the vision capability rather than as a divergence."
 		],
 		"extras": {
@@ -92,12 +92,12 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 		"compat": {
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
-			"supportsUsageInStreaming": false,
+			"supportsUsageInStreaming": true,
 			"supportsFinishReason": true,
 			"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, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming false (2026-09-13): pi-ai only sends stream_options when this is not false, and NaN's published schema does not document it, so the conservative default stays false (sanitizer removes stream_options, usage reads zero). A user who has confirmed that their model returns a streaming usage chunk can opt in per model with a models.json compat override (supportsUsageInStreaming: true); the sanitizer then forwards stream_options instead of deleting it (issue #4)."
+			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming true (2026-09-16, issue #7): NaN's published schema is silent about stream_options, but the live gateway honors it — two identical streaming calls per model, differing only in stream_options: { include_usage: true }, returned 0 usage chunks without it and exactly 1 with it (prompt/completion/reasoning/cached token counts) on deepseek-v4-flash, glm5.3-flash, qwen3.6, mimo-v2.5 and gemma4, and a real pi session then recorded token counts where it recorded zeros. pi-ai only sends stream_options when this is not false, and the sanitizer forwards it when the model declares true, so chat models opt in by default and usage is reported (issue #4). A model that does not report streaming usage can still opt out per model with a models.json compat override (supportsUsageInStreaming: false); the sanitizer then strips stream_options and the payload stays strict."
 		],
 		"extras": {
 			"id": "gemma4",
@@ -155,18 +155,18 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 		"compat": {
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
-			"supportsUsageInStreaming": false,
+			"supportsUsageInStreaming": true,
 			"supportsFinishReason": true,
 			"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, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming false (2026-09-13): pi-ai only sends stream_options when this is not false, and NaN's published schema does not document it, so the conservative default stays false (sanitizer removes stream_options, usage reads zero). A user who has confirmed that their model returns a streaming usage chunk can opt in per model with a models.json compat override (supportsUsageInStreaming: true); the sanitizer then forwards stream_options instead of deleting it (issue #4)."
+			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming true (2026-09-16, issue #7): NaN's published schema is silent about stream_options, but the live gateway honors it — two identical streaming calls per model, differing only in stream_options: { include_usage: true }, returned 0 usage chunks without it and exactly 1 with it (prompt/completion/reasoning/cached token counts) on deepseek-v4-flash, glm5.3-flash, qwen3.6, mimo-v2.5 and gemma4, and a real pi session then recorded token counts where it recorded zeros. pi-ai only sends stream_options when this is not false, and the sanitizer forwards it when the model declares true, so chat models opt in by default and usage is reported (issue #4). A model that does not report streaming usage can still opt out per model with a models.json compat override (supportsUsageInStreaming: false); the sanitizer then strips stream_options and the payload stays strict."
 		],
 		"extras": {
 			"id": "glm5.3-flash",
 			"name": "GLM-5.3-Flash",
 			"description": "Native multimodal GLM model for efficient coding and long-horizon agent tasks",
-			"family": "glm",
+			"family": "glm-flash",
 			"attachment": true,
 			"reasoning": true,
 			"reasoning_options": [],
@@ -214,12 +214,12 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 		"compat": {
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
-			"supportsUsageInStreaming": false,
+			"supportsUsageInStreaming": true,
 			"supportsFinishReason": true,
 			"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, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming false (2026-09-13): pi-ai only sends stream_options when this is not false, and NaN's published schema does not document it, so the conservative default stays false (sanitizer removes stream_options, usage reads zero). A user who has confirmed that their model returns a streaming usage chunk can opt in per model with a models.json compat override (supportsUsageInStreaming: true); the sanitizer then forwards stream_options instead of deleting it (issue #4)."
+			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming true (2026-09-16, issue #7): NaN's published schema is silent about stream_options, but the live gateway honors it — two identical streaming calls per model, differing only in stream_options: { include_usage: true }, returned 0 usage chunks without it and exactly 1 with it (prompt/completion/reasoning/cached token counts) on deepseek-v4-flash, glm5.3-flash, qwen3.6, mimo-v2.5 and gemma4, and a real pi session then recorded token counts where it recorded zeros. pi-ai only sends stream_options when this is not false, and the sanitizer forwards it when the model declares true, so chat models opt in by default and usage is reported (issue #4). A model that does not report streaming usage can still opt out per model with a models.json compat override (supportsUsageInStreaming: false); the sanitizer then strips stream_options and the payload stays strict."
 		],
 		"extras": {
 			"id": "mimo-v2.5",
@@ -274,12 +274,12 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 		"compat": {
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
-			"supportsUsageInStreaming": false,
+			"supportsUsageInStreaming": true,
 			"supportsFinishReason": true,
 			"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, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming false (2026-09-13): pi-ai only sends stream_options when this is not false, and NaN's published schema does not document it, so the conservative default stays false (sanitizer removes stream_options, usage reads zero). A user who has confirmed that their model returns a streaming usage chunk can opt in per model with a models.json compat override (supportsUsageInStreaming: true); the sanitizer then forwards stream_options instead of deleting it (issue #4)."
+			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming true (2026-09-16, issue #7): NaN's published schema is silent about stream_options, but the live gateway honors it — two identical streaming calls per model, differing only in stream_options: { include_usage: true }, returned 0 usage chunks without it and exactly 1 with it (prompt/completion/reasoning/cached token counts) on deepseek-v4-flash, glm5.3-flash, qwen3.6, mimo-v2.5 and gemma4, and a real pi session then recorded token counts where it recorded zeros. pi-ai only sends stream_options when this is not false, and the sanitizer forwards it when the model declares true, so chat models opt in by default and usage is reported (issue #4). A model that does not report streaming usage can still opt out per model with a models.json compat override (supportsUsageInStreaming: false); the sanitizer then strips stream_options and the payload stays strict."
 		],
 		"extras": {
 			"id": "qwen3.6",
@@ -337,12 +337,12 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 		"compat": {
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
-			"supportsUsageInStreaming": false,
+			"supportsUsageInStreaming": true,
 			"supportsFinishReason": true,
 			"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, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming false (2026-09-13): pi-ai only sends stream_options when this is not false, and NaN's published schema does not document it, so the conservative default stays false (sanitizer removes stream_options, usage reads zero). A user who has confirmed that their model returns a streaming usage chunk can opt in per model with a models.json compat override (supportsUsageInStreaming: true); the sanitizer then forwards stream_options instead of deleting it (issue #4).",
+			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming true (2026-09-16, issue #7): NaN's published schema is silent about stream_options, but the live gateway honors it — two identical streaming calls per model, differing only in stream_options: { include_usage: true }, returned 0 usage chunks without it and exactly 1 with it (prompt/completion/reasoning/cached token counts) on deepseek-v4-flash, glm5.3-flash, qwen3.6, mimo-v2.5 and gemma4, and a real pi session then recorded token counts where it recorded zeros. pi-ai only sends stream_options when this is not false, and the sanitizer forwards it when the model declares true, so chat models opt in by default and usage is reported (issue #4). A model that does not report streaming usage can still opt out per model with a models.json compat override (supportsUsageInStreaming: false); the sanitizer then strips stream_options and the payload stays strict.",
 			"contextWindow 262,144: the earlier 1,000,000 override (maintainer-confirmed 2026-09-05) was withdrawn 2026-09-07 — the updated https://nan.builders/docs/models still states '262K token context, the model's native window' and models.dev agrees at 262,144; NaN docs are treated as the most reliable source (maintainer instruction, 2026-09-07)."
 		],
 		"extras": {
@@ -382,13 +382,13 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 export const GENERATED_CATALOG_META = {
 	source: "https://models.dev/api.json",
 	modelsDevProvider: "nan",
-	fetchedAt: "2026-09-14T20:40:55.922Z",
+	fetchedAt: "2026-09-21T23:54:45.052Z",
 	modelCount: 6,
 	models: ["deepseek-v4-flash","gemma4","glm5.3-flash","mimo-v2.5","qwen3.6","qwen3.8-flash"],
 	notes: [
 	"live-only: \"glm5.3\" kept out of the static catalog (premium-tier model (models.dev now documents it with 1M context / 131,072 max output; NaN docs https://nan.builders/docs/models + https://nan.builders/openapi.json, checked 2026-09-13) kept live-only so a non-premium key never sees a model it cannot call when the live /models fetch is unavailable; premium keys still get it via the /models refresh with conservative placeholder limits)",
 	"provider-removed: \"glm5.2\" excluded from the catalog (removed by NaN (2026-09-05); absent from the official chat model list in https://nan.builders/openapi.json and https://nan.builders/docs/models (checked 2026-09-07) while models.dev provider nan still listed it — excluded so regeneration does not resurrect it)",
-	"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming false (2026-09-13): pi-ai only sends stream_options when this is not false, and NaN's published schema does not document it, so the conservative default stays false (sanitizer removes stream_options, usage reads zero). A user who has confirmed that their model returns a streaming usage chunk can opt in per model with a models.json compat override (supportsUsageInStreaming: true); the sanitizer then forwards stream_options instead of deleting it (issue #4).",
+	"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming true (2026-09-16, issue #7): NaN's published schema is silent about stream_options, but the live gateway honors it — two identical streaming calls per model, differing only in stream_options: { include_usage: true }, returned 0 usage chunks without it and exactly 1 with it (prompt/completion/reasoning/cached token counts) on deepseek-v4-flash, glm5.3-flash, qwen3.6, mimo-v2.5 and gemma4, and a real pi session then recorded token counts where it recorded zeros. pi-ai only sends stream_options when this is not false, and the sanitizer forwards it when the model declares true, so chat models opt in by default and usage is reported (issue #4). A model that does not report streaming usage can still opt out per model with a models.json compat override (supportsUsageInStreaming: false); the sanitizer then strips stream_options and the payload stays strict.",
 	"input includes image: NaN serves the Vision-Exp variant ('takes images as input', https://nan.builders/docs/models; the image_url content-parts in https://nan.builders/openapi.json list deepseek-v4-flash among the vision models). models.dev provider nan also lists text+image now (DeepSeek V4.1 Flash entry, checked 2026-09-13; its 2026-09-07 snapshot listed text only), so this override is kept as a pin for the vision capability rather than as a divergence.",
 	"contextWindow 262,144: the earlier 1,000,000 override (maintainer-confirmed 2026-09-05) was withdrawn 2026-09-07 — the updated https://nan.builders/docs/models still states '262K token context, the model's native window' and models.dev agrees at 262,144; NaN docs are treated as the most reliable source (maintainer instruction, 2026-09-07)."
 ],

package/src/fetch-models.ts

@@ -177,10 +177,11 @@ export function mergeLiveWithGenerated(
 			// gateway cuts SSE streams before finish_reason, so supportsFinishReason
 			// must stay true (pi-ai then raises the retryable "Stream ended without
 			// finish_reason" instead of silently stalling), and
-			// supportsUsageInStreaming stays false because NaN's schema does not
-			// document `stream_options`: the sanitizer strips it unless the model's
-			// effective compat opts in (issue #4), so false matches the default wire
-			// payload.
+			// supportsUsageInStreaming is true because the live gateway honors
+			// `stream_options.include_usage` even though the published schema is
+			// silent (issue #7, measured 2026-09-16): the sanitizer forwards the
+			// field and pi reports real token counts. A model can still opt out
+			// with a models.json override of false.
 			models.push({
 				id,
 				name: id,
@@ -192,7 +193,7 @@ export function mergeLiveWithGenerated(
 				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
 				contextWindow: UNKNOWN_MODEL_LIMITS.contextWindow,
 				maxTokens: UNKNOWN_MODEL_LIMITS.maxTokens,
-				compat: { supportsFinishReason: true, supportsUsageInStreaming: false },
+				compat: { supportsFinishReason: true, supportsUsageInStreaming: true },
 			});
 			unknown.push(id);
 		}

package/src/index.ts

@@ -28,6 +28,7 @@
 import type { ContextEvent, ExtensionAPI, ProviderConfig } from "@earendil-works/pi-coding-agent";
 import type { Provider } from "@earendil-works/pi-ai";
 import { registerNanMcpCommand } from "./commands.ts";
+import { registerNanUsageCommand } from "./usage.ts";
 import {
 	crossModelThinkingGuardEnabled,
 	stripCrossModelThinking,
@@ -109,6 +110,7 @@ function registerMcpToolsCompat(pi: ExtensionAPI): void {
 	if (mediaMcpEnabled()) registerMediaTools();
 	if (typeof pi.registerCommand === "function") {
 		registerNanMcpCommand(pi, { registerWebSearchTools: registerSearchTool, registerMediaTools });
+		registerNanUsageCommand(pi);
 	}
 }
 

package/src/openai-compat-sanitizer.ts

@@ -33,14 +33,16 @@
  *     not silently lost.
  *  4. Top-level fields NaN's schema does not list: `store` and
  *     `stream_options`. These are opt-in/usage fields pi-ai sends by default
- *     for a "standard" provider; NaN does not document them, so they are
- *     removed by default. `stream_options` is the one exception that can be
- *     explicitly opted into: when the model's effective
- *     `compat.supportsUsageInStreaming` is true (a catalog flag or a user
- *     `models.json` override), the caller has confirmed the gateway reports
- *     usage and `stream_options` is preserved — deleting it unconditionally
- *     would silently zero out `message.usage` (issue #4). `store` is always
- *     removed.
+ *     for a "standard" provider; NaN's published schema does not document
+ *     them, so they are removed by default. `stream_options` is the one
+ *     exception that can be explicitly opted into: when the model's effective
+ *     `compat.supportsUsageInStreaming` is true (the catalog default for chat
+ *     models since issue #7 — the live gateway was measured honoring
+ *     `include_usage` on 2026-09-16 — or a user `models.json` override), the
+ *     gateway reports usage and `stream_options` is preserved — deleting it
+ *     unconditionally would silently zero out `message.usage` (issue #4).
+ *     A per-model override of `false` keeps the strict payload. `store` is
+ *     always removed.
  *  5. An EMPTY `tools` array. Verified against the live gateway (2026-09-09):
  *     NaN rejects `tools: []` with the same 400, while `stream: true`, a
  *     `system` message, string content, and a `tool` role message are all

package/src/pi-ai-loader.ts

@@ -0,0 +1,228 @@
+/**
+ * Resolve the `openai-completions` streaming API factory from the **same
+ * `@earendil-works/pi-ai` package instance** the host resolved for this
+ * extension's bare-root import — never from a bare subpath specifier.
+ *
+ * ## Why this module exists (issue #8)
+ *
+ * `src/provider-factory.ts` used to fall back to a bare SUBPATH import of the
+ * `api/openai-completions.lazy` entry. That is not the same module as the bare
+ * root on every runtime. On pi-web's
+ * sessiond-on-Bun loader path the bare root `@earendil-works/pi-ai` is NOT
+ * aliased to pi's `/compat` entrypoint: it resolves to the host's pi-ai 0.87
+ * **core** build (whose namespace has no `openAICompletionsApi`), while the
+ * bare subpath resolves, from the extension's own tree, to a stale hoisted
+ * `@earendil-works/pi-ai@0.85.1`. That copy's `estimateMessageTokens` has no
+ * `system` branch, so pi 0.87's string-content `system` transcript message is
+ * iterated character-by-character and crashes on
+ * `undefined is not an object (evaluating 'block.name.length')` — before the
+ * request is ever sent, so it reads like a NaN/gateway failure.
+ *
+ * `import.meta.resolve("@earendil-works/pi-ai")` returns the *same instance*
+ * the bare-root static import used in every environment measured (both the
+ * host's 0.87 core on pi-web, and the extension-tree copy under plain
+ * node/jiti). It is therefore the anchor: derive a **file URL** for the
+ * sibling `api/openai-completions.lazy.js` (then `compat.js`) from that
+ * root and dynamic-import the URL. A file URL bypasses package resolution
+ * entirely, so the loaded module is guaranteed to be the host's instance.
+ *
+ * Under the bundled CLI / Node-mode aliases / compiled binary, the bare root
+ * is the compat entrypoint and already exposes the factory, so the first
+ * branch wins and nothing is resolved.
+ *
+ * **Contract:** no bare `@earendil-works/pi-ai/<subpath>` specifier is ever
+ * imported from `src/` (static or dynamic). When neither the root nor the
+ * host-derived candidates provide the factory, resolution fails loudly with
+ * `PiAiStreamingApiResolutionError` instead of silently loading a stale copy.
+ *
+ * Guarded by `test/issue-8-pi-ai-instance.test.ts` and
+ * `test/extension-load.test.ts`.
+ */
+
+import * as piAi from "@earendil-works/pi-ai";
+import type { ProviderStreams } from "@earendil-works/pi-ai";
+import { createRequire } from "node:module";
+
+/** The only pi-ai specifier this package may import. */
+export const PI_AI_PACKAGE_SPECIFIER = "@earendil-works/pi-ai";
+
+/** Export name of the openai-completions lazy factory on compat/lazy entrypoints. */
+export const OPENAI_COMPLETIONS_FACTORY_EXPORT = "openAICompletionsApi";
+
+/** Package-relative path of the lazy openai-completions entrypoint. */
+export const OPENAI_COMPLETIONS_LAZY_ENTRY = "api/openai-completions.lazy.js";
+
+/** Package-relative path of pi-ai's compat entrypoint (secondary candidate). */
+export const PI_AI_COMPAT_ENTRY = "compat.js";
+
+/** pi-ai's lazy API factory shape (same as the compat root export). */
+export type OpenAICompletionsApiFactory = () => ProviderStreams;
+
+/** A dynamically imported module namespace. */
+export type ModuleNamespace = Record<string, unknown>;
+
+/**
+ * The resolution seam. Production uses {@link defaultPiAiLoaderHost}; tests
+ * inject a host to prove the loader binds to the resolved instance (and never
+ * to the extension's own tree).
+ */
+export interface PiAiLoaderHost {
+	/** The bare-root namespace this extension statically imported. */
+	readonly namespace: ModuleNamespace;
+	/** Resolve a specifier the way the host runtime does. */
+	resolveSpecifier?(specifier: string): string;
+	/** Load a module by absolute URL (a `file://` URL in the derived path). */
+	importModule(url: string): Promise<ModuleNamespace>;
+}
+
+/**
+ * Thrown when the openai-completions factory cannot be bound to the
+ * host-resolved pi-ai instance. Carries the resolved root and the URLs that
+ * were attempted so the failure is a one-line diagnosis.
+ */
+export class PiAiStreamingApiResolutionError extends Error {
+	readonly resolvedRootUrl?: string;
+	readonly attemptedUrls: readonly string[];
+
+	constructor(
+		message: string,
+		options: { resolvedRootUrl?: string; attemptedUrls?: readonly string[] } = {},
+	) {
+		super(message);
+		this.name = "PiAiStreamingApiResolutionError";
+		this.resolvedRootUrl = options.resolvedRootUrl;
+		this.attemptedUrls = options.attemptedUrls ?? [];
+	}
+}
+
+/** Extract the openai-completions factory from a module namespace, if present. */
+export function openAICompletionsApiFrom(namespace: unknown): OpenAICompletionsApiFactory | undefined {
+	if (namespace === null || typeof namespace !== "object") return undefined;
+	const candidate = (namespace as ModuleNamespace)[OPENAI_COMPLETIONS_FACTORY_EXPORT];
+	return typeof candidate === "function" ? (candidate as OpenAICompletionsApiFactory) : undefined;
+}
+
+/**
+ * `import.meta.resolve` is absent from bun-types' `ImportMeta`, so read it
+ * through an explicit shape. Bun/Node expose it at runtime; when it is missing
+ * or throws, `createRequire` resolves the same bare root from this module.
+ */
+type ImportMetaWithResolve = ImportMeta & { resolve?: (specifier: string) => string };
+
+const defaultPiAiLoaderHost: PiAiLoaderHost = {
+	namespace: piAi as unknown as ModuleNamespace,
+	resolveSpecifier(specifier: string): string {
+		const meta = import.meta as ImportMetaWithResolve;
+		if (typeof meta.resolve === "function") {
+			try {
+				const resolved = meta.resolve(specifier);
+				if (typeof resolved === "string" && resolved.length > 0) return resolved;
+			} catch {
+				// Fall through to createRequire — same bare root, same instance.
+			}
+		}
+		return createRequire(import.meta.url).resolve(specifier);
+	},
+	importModule: (url: string) => import(url) as Promise<ModuleNamespace>,
+};
+
+/** Cached result of the default-host resolution; injected hosts bypass it. */
+let defaultHostCache: OpenAICompletionsApiFactory | undefined;
+
+/** Build the candidate file URLs from the host-resolved package root. */
+function candidateUrlsFor(rootUrl: string): { rootDir: URL; candidates: string[] } {
+	const rootDir = new URL("./", new URL(rootUrl));
+	return {
+		rootDir,
+		candidates: [
+			new URL(OPENAI_COMPLETIONS_LAZY_ENTRY, rootDir).href,
+			new URL(PI_AI_COMPAT_ENTRY, rootDir).href,
+		],
+	};
+}
+
+function loudError(
+	rootUrl: string | undefined,
+	attemptedUrls: readonly string[],
+	lastError: Error | undefined,
+): PiAiStreamingApiResolutionError {
+	const lines = [
+		`Could not resolve "${OPENAI_COMPLETIONS_FACTORY_EXPORT}" from the host-resolved "${PI_AI_PACKAGE_SPECIFIER}" instance.`,
+		`Resolved root: ${rootUrl ?? "<unresolved>"}`,
+		attemptedUrls.length > 0
+			? `Attempted URLs:\n${attemptedUrls.map((url) => `  - ${url}`).join("\n")}`
+			: "Attempted URLs: none (package root resolution failed)",
+		lastError ? `Last error: ${lastError.message}` : undefined,
+		"",
+		"This provider refuses to load a stale @earendil-works/pi-ai from the extension's own npm tree (issue #8).",
+		"On pi-web's sessiond-on-Bun loader the bare root is not mapped to pi's /compat entrypoint, so the",
+		"factory must be imported from a file URL derived from import.meta.resolve(...) — never a bare subpath.",
+	];
+	return new PiAiStreamingApiResolutionError(lines.filter((line) => line !== undefined).join("\n"), {
+		resolvedRootUrl: rootUrl,
+		attemptedUrls,
+	});
+}
+
+/**
+ * @param host Resolution seam; omit in production.
+ * @returns The openai-completions lazy API factory from the host's pi-ai instance.
+ * @throws PiAiStreamingApiResolutionError when no candidate can be bound.
+ */
+export async function resolveOpenAICompletionsApi(
+	host?: PiAiLoaderHost,
+): Promise<OpenAICompletionsApiFactory> {
+	const usesDefaultHost = host === undefined;
+	if (usesDefaultHost && defaultHostCache) return defaultHostCache;
+	const activeHost = host ?? defaultPiAiLoaderHost;
+
+	// 1. Compat root (bundled CLI / Node aliases / compiled binary): the bare
+	//    root itself re-exports the factory — no resolution needed.
+	const fromRoot = openAICompletionsApiFrom(activeHost.namespace);
+	if (fromRoot) {
+		if (usesDefaultHost) defaultHostCache = fromRoot;
+		return fromRoot;
+	}
+
+	// 2. Core root (pi-web on Bun): anchor to the host-resolved package root.
+	if (typeof activeHost.resolveSpecifier !== "function") {
+		throw loudError(undefined, [], undefined);
+	}
+
+	let rootUrl: string | undefined;
+	try {
+		rootUrl = activeHost.resolveSpecifier(PI_AI_PACKAGE_SPECIFIER);
+	} catch (error) {
+		throw loudError(undefined, [], error instanceof Error ? error : new Error(String(error)));
+	}
+	if (!rootUrl) throw loudError(undefined, [], undefined);
+
+	// 3. Derive file URLs from the resolved root. The directory-prefix guard is
+	//    the same-package-instance assertion: a candidate must stay inside the
+	//    package the host resolved.
+	const { rootDir, candidates } = candidateUrlsFor(rootUrl);
+	const attemptedUrls: string[] = [];
+	let lastError: Error | undefined;
+	for (const candidate of candidates) {
+		if (!candidate.startsWith(rootDir.href)) {
+			throw loudError(
+				rootUrl,
+				attemptedUrls,
+				new Error(`candidate "${candidate}" escapes the resolved package root "${rootDir.href}"`),
+			);
+		}
+		attemptedUrls.push(candidate);
+		try {
+			const factory = openAICompletionsApiFrom(await activeHost.importModule(candidate));
+			if (factory) {
+				if (usesDefaultHost) defaultHostCache = factory;
+				return factory;
+			}
+			lastError = new Error(`"${OPENAI_COMPLETIONS_FACTORY_EXPORT}" is not exported by ${candidate}`);
+		} catch (error) {
+			lastError = error instanceof Error ? error : new Error(String(error));
+		}
+	}
+
+	throw loudError(rootUrl, attemptedUrls, lastError);
+}

package/src/provider-factory.ts

@@ -18,6 +18,10 @@
  * 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.
+ *
+ * Streaming API resolution: bare root under pi's compat alias is the instance
+ * anchor; otherwise a file URL from import.meta.resolve; never a bare subpath
+ * (loud failure — issue #8). Full logic in src/pi-ai-loader.ts.
  */
 
 import * as piAi from "@earendil-works/pi-ai";
@@ -33,6 +37,7 @@ import {
 	resolveCatalog,
 	type CatalogSource,
 } from "./fetch-models.ts";
+import { resolveOpenAICompletionsApi } from "./pi-ai-loader.ts";
 import { sanitizeOpenAICompatPayload } from "./openai-compat-sanitizer.ts";
 
 export interface OpenAICompatibleProviderConfig {
@@ -53,51 +58,23 @@ 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;
-}
-
 /**
  * Wrap an api so every outgoing `/chat/completions` payload is made conformant
  * to the strict OpenAI Chat Completions schema NaN enforces (see
  * ./openai-compat-sanitizer.ts). NaN returns HTTP 400 `Invalid request. Check
  * your request parameters.` for any payload that violates it — including a
  * replayed assistant message with a `toolCall` block inside `content`, a
- * `reasoning_details` field, or undocumented top-level fields like `store` /
- * `stream_options`. Sanitizing via the `onPayload` hook works regardless of
+ * `reasoning_details` field, or the undocumented top-level `store` field.
+ * Sanitizing via the `onPayload` hook works regardless of
  * which pi-ai version the runtime bundles, so the fix is not tied to a
  * specific upstream build.
  *
  * `stream_options` is the one field whose removal is conditional: when the
- * model's effective `compat.supportsUsageInStreaming` is true (catalog value
- * or user `models.json` override), pi-ai requested usage and the gateway will
- * return it — stripping the field would silently zero `message.usage`
- * (issue #4). Every other model keeps the strict payload.
+ * model's effective `compat.supportsUsageInStreaming` is true (the catalog
+ * default for chat models since issue #7, or a user `models.json` override),
+ * pi-ai requested usage and the gateway will return it — stripping the field
+ * would silently zero `message.usage` (issue #4). Every other model keeps the
+ * strict payload.
  *
  * Any caller-supplied `onPayload` (e.g. pi's own debug/passthrough hook) is
  * preserved and chained AFTER sanitization, so the final payload is always
@@ -156,8 +133,10 @@ export function wrapApiForStrictSanitization(api: ProviderStreams): ProviderStre
  * - 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: the openai-completions streaming implementation (see
- *   `resolveOpenAICompletionsApi` for why this is resolved dynamically).
+ * - api: the openai-completions streaming implementation resolved via
+ *   `resolveOpenAICompletionsApi` (bare root under pi's compat alias as
+ *   the instance anchor; otherwise a file URL from import.meta.resolve;
+ *   never a bare subpath — loud failure if unresolved). Issue #8.
  */
 export async function createNanCompatibleProvider(
 	config: OpenAICompatibleProviderConfig,

package/src/usage.ts

@@ -0,0 +1,306 @@
+/**
+ * `/nan-usage` — slash command showing NaN quota status per model.
+ *
+ * NaN's quota endpoint (`cloud-api.nan.builders/api/usage/quota`) requires
+ * a session token (not API key auth). The token is obtained via the NaN CLI
+ * login flow (email → link → `nan_session` cookie), stored in
+ * `~/.config/nan/session.json`.
+ *
+ * This command auto-detects the nan-cli session file. No env vars needed —
+ * just run `nan auth login` once and `/nan-usage` works.
+ *
+ * Quota sources: https://nan.builders/docs/models (checked 2026-09-21)
+ */
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// ── Known quota limits per model (from NaN docs) ──────────────────────────
+
+export interface ModelQuota {
+	/** Model ID as used in API calls. */
+	model: string;
+	/** Human-readable name. */
+	label: string;
+	/** Monthly token cap (0 = uncapped). */
+	monthlyCap: number;
+	/** Rolling 4h window cap in tokens (0 = none). */
+	rollingWindowCap: number;
+	/** Rolling window duration in hours. */
+	rollingWindowHours: number;
+	/** Whether this model is premium-tier (glm5.3). */
+	premium: boolean;
+}
+
+export const MODEL_QUOTAS: readonly ModelQuota[] = [
+	{ model: "deepseek-v4-flash", label: "DeepSeek V4 Flash", monthlyCap: 3_000_000_000, rollingWindowCap: 0, rollingWindowHours: 0, premium: false },
+	{ model: "mimo-v2.5", label: "MiMo V2.5", monthlyCap: 1_000_000_000, rollingWindowCap: 0, rollingWindowHours: 0, premium: false },
+	{ model: "qwen3.6", label: "Qwen 3.6", monthlyCap: 0, rollingWindowCap: 0, rollingWindowHours: 0, premium: false },
+	{ model: "gemma4", label: "Gemma 4", monthlyCap: 0, rollingWindowCap: 0, rollingWindowHours: 0, premium: false },
+	{ model: "qwen3.8-flash", label: "Qwen 3.8 Flash", monthlyCap: 500_000_000, rollingWindowCap: 0, rollingWindowHours: 0, premium: false },
+	{ model: "glm5.3-flash", label: "GLM 5.3 Flash", monthlyCap: 2_000_000_000, rollingWindowCap: 0, rollingWindowHours: 0, premium: false },
+	{ model: "glm5.3", label: "GLM 5.3", monthlyCap: 3_000_000_000, rollingWindowCap: 400_000_000, rollingWindowHours: 4, premium: true },
+];
+
+// ── Dashboard API types ───────────────────────────────────────────────────
+
+interface DashboardModelQuota {
+	model: string;
+	tokensUsed: number;
+	cap: number;
+	percentage: number;
+	resetAt: string | null;
+	windowHours: number | null;
+}
+
+interface DashboardUncappedModelQuota {
+	model: string;
+	tokensUsed: number;
+	resetAt: string | null;
+	windowHours: number | null;
+}
+
+interface DashboardQuotaResponse {
+	periodStart: string;
+	models: Array<{
+		model: string;
+		tokensUsed: number;
+		cap: number;
+		windowHours?: number;
+		periodEnd?: string;
+	}>;
+}
+
+// ── nan-cli session reader ────────────────────────────────────────────────
+
+interface NanCliSession {
+	token: string;
+}
+
+/** Read the nan_session token from ~/.config/nan/session.json (shared with nan-cli). */
+function readNanCliSessionToken(): string | undefined {
+	try {
+		const sessionPath = join(homedir(), ".config", "nan", "session.json");
+		const data = readFileSync(sessionPath, "utf8");
+		const session = JSON.parse(data) as NanCliSession;
+		if (typeof session === "object" && session !== null && typeof session.token === "string" && session.token.length > 0) {
+			return session.token;
+		}
+	} catch {
+		// File doesn't exist or is invalid.
+	}
+	return undefined;
+}
+
+// ── Time helpers ──────────────────────────────────────────────────────────
+
+function formatDuration(ms: number): string {
+	if (ms <= 0) return "already reset";
+	const totalSeconds = Math.floor(ms / 1000);
+	const days = Math.floor(totalSeconds / 86400);
+	const hours = Math.floor((totalSeconds % 86400) / 3600);
+	const minutes = Math.floor((totalSeconds % 3600) / 60);
+	const seconds = totalSeconds % 60;
+
+	const parts: string[] = [];
+	if (days > 0) parts.push(`${days}d`);
+	if (hours > 0) parts.push(`${hours}h`);
+	if (minutes > 0) parts.push(`${minutes}m`);
+	parts.push(`${seconds}s`);
+	return parts.join(" ");
+}
+
+function getNextBillingReset(): Date {
+	const now = new Date();
+	const year = now.getUTCFullYear();
+	const month = now.getUTCMonth();
+	return new Date(Date.UTC(year, month + 1, 0, 0, 0, 0));
+}
+
+function formatTokens(n: number): string {
+	if (n >= 1_000_000_000) return `${(n / 1_000_000_000).toFixed(1)}B`;
+	if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+	if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+	return String(n);
+}
+
+function progressBar(percentage: number, width = 20): string {
+	const filled = Math.round((percentage / 100) * width);
+	const empty = width - filled;
+	return `[${"█".repeat(filled)}${"░".repeat(empty)}]`;
+}
+
+// ── Dashboard client ──────────────────────────────────────────────────────
+
+const DASHBOARD_QUOTA_URL = "https://cloud-api.nan.builders/api/usage/quota";
+const FETCH_TIMEOUT_MS = 10_000;
+
+async function fetchDashboardQuota(token: string): Promise<DashboardQuotaResponse | null> {
+	try {
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+		try {
+			const response = await fetch(DASHBOARD_QUOTA_URL, {
+				method: "GET",
+				headers: { cookie: `nan_session=${token}` },
+				redirect: "manual",
+				cache: "no-store",
+				signal: controller.signal,
+			});
+			if (!response.ok) return null;
+			return (await response.json()) as DashboardQuotaResponse;
+		} finally {
+			clearTimeout(timeout);
+		}
+	} catch {
+		return null;
+	}
+}
+
+function parseDashboardQuota(data: DashboardQuotaResponse): {
+	capped: DashboardModelQuota[];
+	uncapped: DashboardUncappedModelQuota[];
+} {
+	const capped: DashboardModelQuota[] = [];
+	const uncapped: DashboardUncappedModelQuota[] = [];
+	const seen = new Set<string>();
+
+	for (const entry of data.models) {
+		if (seen.has(entry.model)) continue;
+		seen.add(entry.model);
+
+		if (entry.cap === 0) {
+			uncapped.push({
+				model: entry.model,
+				tokensUsed: entry.tokensUsed,
+				resetAt: entry.periodEnd ?? null,
+				windowHours: entry.windowHours ?? null,
+			});
+		} else {
+			capped.push({
+				model: entry.model,
+				tokensUsed: entry.tokensUsed,
+				cap: entry.cap,
+				percentage: (entry.tokensUsed / entry.cap) * 100,
+				resetAt: entry.periodEnd ?? null,
+				windowHours: entry.windowHours ?? null,
+			});
+		}
+	}
+
+	return { capped, uncapped };
+}
+
+// ── Message builders ──────────────────────────────────────────────────────
+
+function buildStaticMessage(): string {
+	const resetDate = getNextBillingReset();
+	const timeUntilReset = resetDate.getTime() - Date.now();
+
+	const lines: string[] = [
+		"📊 NaN Quota Status (static limits)",
+		"",
+		`⏱️  Next billing reset: ${resetDate.toISOString().split("T")[0]} UTC (${formatDuration(timeUntilReset)})`,
+		"",
+		"Model                        Monthly Cap",
+		"─".repeat(45),
+	];
+
+	for (const quota of MODEL_QUOTAS) {
+		const capStr = quota.monthlyCap > 0 ? formatTokens(quota.monthlyCap) : "uncapped";
+		const premiumStr = quota.premium ? " 👑" : "";
+		const rollingStr = quota.rollingWindowCap > 0
+			? ` (rolling ${formatTokens(quota.rollingWindowCap)}/${quota.rollingWindowHours}h)`
+			: "";
+
+		lines.push(`${quota.label.padEnd(28)} ${capStr}${premiumStr}${rollingStr}`);
+	}
+
+	lines.push("");
+	lines.push("💡 Run `nan auth login` to see real usage data.");
+
+	return lines.join("\n");
+}
+
+function buildDashboardMessage(
+	capped: DashboardModelQuota[],
+	uncapped: DashboardUncappedModelQuota[],
+): string {
+	const resetDate = getNextBillingReset();
+	const timeUntilReset = resetDate.getTime() - Date.now();
+
+	const lines: string[] = [
+		"📊 NaN Quota Status",
+		"",
+		`⏱️  Next billing reset: ${resetDate.toISOString().split("T")[0]} UTC (${formatDuration(timeUntilReset)})`,
+		"",
+	];
+
+	if (capped.length > 0) {
+		lines.push("Models with monthly caps:");
+		lines.push("");
+		for (const m of capped) {
+			const quota = MODEL_QUOTAS.find((q) => q.model === m.model);
+			const label = quota?.label ?? m.model;
+			const pct = m.percentage.toFixed(1);
+			const remaining = m.cap - m.tokensUsed;
+			lines.push(`${label}:`);
+			lines.push(`  ${progressBar(m.percentage)} ${pct}%`);
+			lines.push(`  Used: ${formatTokens(m.tokensUsed)} / ${formatTokens(m.cap)} (${formatTokens(remaining)} remaining)`);
+			if (m.windowHours) {
+				lines.push(`  Rolling window: ${m.windowHours}h`);
+			}
+			lines.push("");
+		}
+	}
+
+	if (uncapped.length > 0) {
+		lines.push("Uncapped models:");
+		lines.push("");
+		for (const m of uncapped) {
+			const quota = MODEL_QUOTAS.find((q) => q.model === m.model);
+			const label = quota?.label ?? m.model;
+			lines.push(`${label}: ${formatTokens(m.tokensUsed)} used`);
+		}
+		lines.push("");
+	}
+
+	if (capped.length === 0 && uncapped.length === 0) {
+		lines.push("No usage data. Session may have expired.");
+		lines.push("Run `nan auth login` to refresh.");
+	}
+
+	return lines.join("\n");
+}
+
+// ── Command registration ──────────────────────────────────────────────────
+
+export function registerNanUsageCommand(pi: import("@earendil-works/pi-coding-agent").ExtensionAPI): void {
+	if (typeof pi.registerCommand !== "function") return;
+
+	pi.registerCommand("nan-usage", {
+		description: "Show NaN quota status: token limits, usage, and time until billing reset",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			const token = readNanCliSessionToken();
+
+			if (token) {
+				ctx.ui.notify("Fetching usage from NaN dashboard...", "info");
+				const data = await fetchDashboardQuota(token);
+				if (data) {
+					const { capped, uncapped } = parseDashboardQuota(data);
+					ctx.ui.notify(buildDashboardMessage(capped, uncapped), "info");
+				} else {
+					ctx.ui.notify(
+						"Failed to fetch dashboard data. Session may have expired.\n" +
+						"Run `nan auth login` to refresh.",
+						"warning",
+					);
+				}
+			} else {
+				ctx.ui.notify(buildStaticMessage(), "info");
+			}
+		},
+	});
+}