@gtrabanco/pi-nan-provider 0.6.9 → 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 →

package/README.es.md

@@ -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

@@ -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.9",
+	"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/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-16T19:40:56.569Z
+// 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.
@@ -382,7 +382,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 export const GENERATED_CATALOG_META = {
 	source: "https://models.dev/api.json",
 	modelsDevProvider: "nan",
-	fetchedAt: "2026-09-16T19:40:56.569Z",
+	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: [

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/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,35 +58,6 @@ 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
@@ -157,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");
+			}
+		},
+	});
+}