@aliou/pi-neuralwatt 0.6.3 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-neuralwatt",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -33,7 +33,8 @@
   ],
   "dependencies": {
     "@aliou/pi-utils-settings": "^0.17.0",
-    "@aliou/pi-utils-ui": "^0.4.0"
+    "@aliou/pi-utils-ui": "^0.4.0",
+    "@earendil-works/pi-ai": "$@earendil-works/pi-coding-agent"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/schema.json

@@ -5,6 +5,10 @@
     "NeuralwattConfig": {
       "additionalProperties": false,
       "properties": {
+        "includeHiddenModels": {
+          "description": "Include hidden Neuralwatt models discovered via the authenticated API.",
+          "type": "boolean"
+        },
         "includeLegacyModelIds": {
           "description": "Include legacy Neuralwatt model IDs in the model picker.",
           "type": "boolean"

package/src/config.ts

@@ -30,6 +30,8 @@ export interface NeuralwattConfig {
   subBarIntegration?: boolean;
   /** Include legacy Neuralwatt model IDs in the model picker. */
   includeLegacyModelIds?: boolean;
+  /** Include hidden Neuralwatt models discovered via the authenticated API. */
+  includeHiddenModels?: boolean;
 }
 
 export interface ResolvedNeuralwattConfig {
@@ -37,6 +39,7 @@ export interface ResolvedNeuralwattConfig {
   quotaWarnings: boolean;
   subBarIntegration: boolean;
   includeLegacyModelIds: boolean;
+  includeHiddenModels: boolean;
 }
 
 const DEFAULTS: ResolvedNeuralwattConfig = {
@@ -44,6 +47,7 @@ const DEFAULTS: ResolvedNeuralwattConfig = {
   quotaWarnings: true,
   subBarIntegration: true,
   includeLegacyModelIds: false,
+  includeHiddenModels: false,
 };
 
 export const configLoader = new ConfigLoader<
@@ -157,19 +161,36 @@ export function registerNeuralwattSettings(
                   : "ignore",
               values: ["include", "ignore"],
             },
+            {
+              id: "includeHiddenModels",
+              label: "Hidden models",
+              description:
+                "Include Neuralwatt models that are accessible via API key but not advertised in the public model list",
+              currentValue:
+                (tabConfig?.includeHiddenModels ?? resolved.includeHiddenModels)
+                  ? "include"
+                  : "ignore",
+              values: ["include", "ignore"],
+            },
           ],
         },
       ];
     },
     onSettingChange: (id, newValue, config) => {
-      if (!getLoadedFeatures().has(id as NeuralwattFeatureId)) {
-        return null;
-      }
-
+      // Non-feature toggles are handled first so they are not blocked by the
+      // loaded-features guard (they are managed directly by the provider).
       if (id === "includeLegacyModelIds") {
         return { ...config, includeLegacyModelIds: newValue === "include" };
       }
 
+      if (id === "includeHiddenModels") {
+        return { ...config, includeHiddenModels: newValue === "include" };
+      }
+
+      if (!getLoadedFeatures().has(id as NeuralwattFeatureId)) {
+        return null;
+      }
+
       const enabled = newValue === "enabled";
       switch (id) {
         case "quotaCommand":

package/src/extensions/command-quotas/command.ts

@@ -4,7 +4,7 @@ import {
   getAgentDir,
 } from "@earendil-works/pi-coding-agent";
 import { getNeuralwattApiKey } from "../../lib/env";
-import { fetchQuotas } from "../../utils/quotas";
+import { fetchQuotas } from "../../lib/neuralwatt-api";
 import { QuotasComponent } from "./components/quotas-display";
 
 function missingAuthMessage(): string {

package/src/extensions/provider/index.ts

@@ -1,4 +1,8 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getApiProvider } from "@earendil-works/pi-ai";
+import type {
+  ExtensionAPI,
+  ProviderModelConfig,
+} from "@earendil-works/pi-coding-agent";
 import {
   configLoader,
   emitConfigUpdated,
@@ -9,23 +13,35 @@ import {
   registerNeuralwattSettings,
 } from "../../config";
 import { getNeuralwattApiKey } from "../../lib/env";
+import { fetchQuotas } from "../../lib/neuralwatt-api";
 import type { NeuralwattQuotas } from "../../types/quota-api";
 import {
   NEURALWATT_QUOTAS_REQUEST_EVENT,
   NEURALWATT_QUOTAS_UPDATED_EVENT,
   type NeuralwattQuotasUpdatedPayload,
 } from "../../types/quota-events";
-import { fetchQuotas } from "../../utils/quotas";
 import { normalizeNeuralwattContextOverflowError } from "./context-overflow";
-import { getNeuralwattModels } from "./models";
+import { getNeuralwattModels, loadHiddenModels } from "./models";
 import { buildQuotasFromHeaders, fetchRequestedQuotas } from "./quota-store";
+import {
+  type NeuralwattRateLimitInfo,
+  normalizeNeuralwattRateLimitError,
+  parseRateLimitHeaders,
+} from "./rate-limit-error";
+import { updateQuotasFromSseComment } from "./sse-quotas";
+import { wrapNeuralwattStreamSimple } from "./stream-simple";
 
 const HEADER_EMIT_THROTTLE_MS = 5_000;
 
-function registerNeuralwattProvider(pi: ExtensionAPI): void {
-  const { includeLegacyModelIds } = configLoader.getConfig();
+function registerNeuralwattProvider(
+  pi: ExtensionAPI,
+  onSseQuota: (line: string) => void,
+  hiddenModels: ProviderModelConfig[] = [],
+): void {
+  const { includeLegacyModelIds, includeHiddenModels } =
+    configLoader.getConfig();
 
-  pi.registerProvider("neuralwatt", {
+  const config: Parameters<ExtensionAPI["registerProvider"]>[1] = {
     baseUrl: "https://api.neuralwatt.com/v1",
     apiKey: "$NEURALWATT_API_KEY",
     api: "openai-completions",
@@ -34,16 +50,42 @@ function registerNeuralwattProvider(pi: ExtensionAPI): void {
       Referer: "https://pi.dev",
       "X-Title": "npm:@aliou/pi-neuralwatt",
     },
-    models: getNeuralwattModels({
-      includeLegacyModelIds,
-    }),
-  });
+    models: [
+      ...getNeuralwattModels({ includeLegacyModelIds }),
+      ...(includeHiddenModels ? hiddenModels : []),
+    ],
+  };
+
+  const provider = getApiProvider("openai-completions");
+  const baseStreamSimple = provider?.streamSimple;
+  if (baseStreamSimple) {
+    config.streamSimple = wrapNeuralwattStreamSimple(
+      baseStreamSimple as never,
+      onSseQuota,
+    ) as never;
+  }
+
+  pi.registerProvider("neuralwatt", config);
 }
 
 export default async function (pi: ExtensionAPI) {
   await configLoader.load();
 
-  registerNeuralwattProvider(pi);
+  let latestQuotas: NeuralwattQuotas | undefined;
+  let hiddenModels: ProviderModelConfig[] = [];
+  let hiddenModelsLoaded = false;
+
+  const handleSseQuota = (line: string) => {
+    const quotas = updateQuotasFromSseComment(latestQuotas, line);
+    if (!quotas || quotas === latestQuotas) return;
+    latestQuotas = quotas;
+    pi.events.emit(NEURALWATT_QUOTAS_UPDATED_EVENT, {
+      quotas,
+      source: "sse",
+    });
+  };
+
+  registerNeuralwattProvider(pi, handleSseQuota);
 
   const loadedFeatures = new Set<NeuralwattFeatureId>();
 
@@ -53,7 +95,7 @@ export default async function (pi: ExtensionAPI) {
   });
 
   pi.events.on(NEURALWATT_CONFIG_UPDATED_EVENT, () => {
-    registerNeuralwattProvider(pi);
+    registerNeuralwattProvider(pi, handleSseQuota, hiddenModels);
   });
 
   let lastHeaderEmitAt = 0;
@@ -67,20 +109,67 @@ export default async function (pi: ExtensionAPI) {
     if (source === "header" && now - lastHeaderEmitAt < HEADER_EMIT_THROTTLE_MS)
       return;
     if (source === "header") lastHeaderEmitAt = now;
+    latestQuotas = quotas;
     pi.events.emit(NEURALWATT_QUOTAS_UPDATED_EVENT, { quotas, source });
   }
 
+  // Stored rate-limit info from the most recent 429 response.
+  // Used in message_end to rewrite the generic error text with
+  // actionable details from Neuralwatt's response headers.
+  let pendingRateLimitInfo: NeuralwattRateLimitInfo | undefined;
+
   pi.on("message_end", (event, ctx) => {
-    const message = normalizeNeuralwattContextOverflowError(
+    // Rewrite rate-limit errors with layer-specific details
+    if (
+      pendingRateLimitInfo &&
+      event.message.role === "assistant" &&
+      event.message.stopReason === "error" &&
+      (event.message.provider === "neuralwatt" ||
+        ctx.model?.provider === "neuralwatt")
+    ) {
+      const message = normalizeNeuralwattRateLimitError(
+        event.message,
+        pendingRateLimitInfo,
+      );
+      pendingRateLimitInfo = undefined;
+      return { message };
+    }
+
+    if (
+      event.message.role === "assistant" &&
+      event.message.stopReason === "error" &&
+      (event.message.provider === "neuralwatt" ||
+        ctx.model?.provider === "neuralwatt") &&
+      event.message.errorMessage?.includes("429")
+    ) {
+      return {
+        message: normalizeNeuralwattRateLimitError(event.message, {
+          layer: "unknown",
+          detail:
+            "Neuralwatt rate limit reached, but Pi did not receive layer-specific rate-limit headers. Retry shortly.",
+        }),
+      };
+    }
+
+    // Rewrite context overflow errors for Pi's native compaction
+    const overflowMessage = normalizeNeuralwattContextOverflowError(
       event.message,
       ctx.model?.provider,
     );
-    if (!message) return;
-    return { message };
+    if (!overflowMessage) return;
+    return { message: overflowMessage };
   });
 
   pi.on("after_provider_response", (event, ctx) => {
     if (ctx.model?.provider !== "neuralwatt") return;
+
+    // Capture rate-limit headers from 429 responses for message_end rewriting
+    if (event.status === 429) {
+      pendingRateLimitInfo = parseRateLimitHeaders(event.headers);
+    } else {
+      pendingRateLimitInfo = undefined;
+    }
+
     const quotas = buildQuotasFromHeaders(event.headers);
     if (!quotas) return;
     emitQuotas(quotas, "header");
@@ -91,11 +180,7 @@ export default async function (pi: ExtensionAPI) {
     quotaRequestInFlight = true;
     try {
       const quotas = await fetchRequestedQuotas(data);
-      if (quotas)
-        pi.events.emit(NEURALWATT_QUOTAS_UPDATED_EVENT, {
-          quotas,
-          source: "api",
-        });
+      if (quotas) emitQuotas(quotas, "api");
     } finally {
       quotaRequestInFlight = false;
     }
@@ -107,6 +192,7 @@ export default async function (pi: ExtensionAPI) {
   });
 
   pi.on("session_start", async (_event, ctx) => {
+    pendingRateLimitInfo = undefined;
     for (const message of configLoader.drainMessages()) {
       ctx.ui.notify(message, "warning");
     }
@@ -115,6 +201,15 @@ export default async function (pi: ExtensionAPI) {
     pi.events.emit(NEURALWATT_EXTENSIONS_REQUEST_EVENT, undefined);
     emitConfigUpdated(pi);
 
+    if (!hiddenModelsLoaded && configLoader.getConfig().includeHiddenModels) {
+      hiddenModelsLoaded = true;
+      const fetched = await loadHiddenModels(ctx.modelRegistry.authStorage);
+      if (fetched.length > 0) {
+        hiddenModels = fetched;
+        registerNeuralwattProvider(pi, handleSseQuota, hiddenModels);
+      }
+    }
+
     if (ctx.model?.provider !== "neuralwatt") return;
     const apiKey = await getNeuralwattApiKey(ctx.modelRegistry.authStorage);
     if (!apiKey) return;

package/src/extensions/provider/models/hidden.ts

@@ -0,0 +1,127 @@
+import type {
+  AuthStorage,
+  ProviderModelConfig,
+} from "@earendil-works/pi-coding-agent";
+import { getNeuralwattApiKey } from "../../../lib/env";
+import { fetchNeuralwattModels } from "../../../lib/neuralwatt-api";
+import type { NeuralwattApiModel } from "../../../types/models-api";
+import { NEURALWATT_MODELS } from "./public-models";
+
+// Per-ID overrides for known hidden models. The authenticated /v1/models endpoint
+// exposes pricing and capabilities, but some Pi-specific behavior (thinking levels,
+// compat flags) has to be supplied by hand.
+const HIDDEN_MODEL_OVERRIDES: Partial<
+  Record<string, Partial<ProviderModelConfig>>
+> = {
+  "glm-5.2-short": {
+    thinkingLevelMap: {
+      minimal: null,
+      low: null,
+      medium: null,
+      high: "high",
+      xhigh: "max",
+    },
+  },
+};
+
+function buildHiddenModel(apiModel: NeuralwattApiModel): ProviderModelConfig {
+  const meta = apiModel.metadata;
+  const reasoning = meta?.capabilities.reasoning ?? false;
+  const override = HIDDEN_MODEL_OVERRIDES[apiModel.id];
+
+  const compat: NonNullable<ProviderModelConfig["compat"]> = {
+    supportsDeveloperRole: false,
+    maxTokensField: "max_tokens",
+  };
+  if (reasoning) {
+    compat.requiresReasoningContentOnAssistantMessages = true;
+  }
+
+  const model: ProviderModelConfig = {
+    id: apiModel.id,
+    name: meta?.display_name ?? apiModel.id,
+    reasoning,
+    input: (meta?.capabilities.vision ? ["text", "image"] : ["text"]) as (
+      | "text"
+      | "image"
+    )[],
+    cost: {
+      input: meta?.pricing.input_per_million ?? 0,
+      output: meta?.pricing.output_per_million ?? 0,
+      cacheRead: meta?.pricing.cached_input_per_million ?? 0,
+      cacheWrite: meta?.pricing.cached_output_per_million ?? 0,
+    },
+    contextWindow: apiModel.max_model_len,
+    maxTokens: meta?.limits.max_output_tokens ?? 65536,
+    compat,
+  };
+
+  if (reasoning) {
+    model.thinkingLevelMap = override?.thinkingLevelMap ?? {
+      minimal: null,
+      low: null,
+      medium: "medium",
+      high: null,
+      xhigh: null,
+    };
+  }
+
+  if (override) {
+    return applyHiddenOverride(model, override);
+  }
+
+  return model;
+}
+
+function applyHiddenOverride(
+  model: ProviderModelConfig,
+  override: Partial<ProviderModelConfig>,
+): ProviderModelConfig {
+  const result: ProviderModelConfig = { ...model };
+
+  if (override.name !== undefined) result.name = override.name;
+  if (override.reasoning !== undefined) result.reasoning = override.reasoning;
+  if (override.input !== undefined) result.input = override.input;
+  if (override.thinkingLevelMap !== undefined) {
+    result.thinkingLevelMap = override.thinkingLevelMap;
+  }
+  if (override.contextWindow !== undefined) {
+    result.contextWindow = override.contextWindow;
+  }
+  if (override.maxTokens !== undefined) result.maxTokens = override.maxTokens;
+  if (override.cost !== undefined) {
+    result.cost = { ...model.cost, ...override.cost };
+  }
+  if (override.compat !== undefined) {
+    result.compat = { ...model.compat, ...override.compat };
+  }
+
+  return result;
+}
+
+/**
+ * Load hidden models from the authenticated /v1/models endpoint.
+ *
+ * Hidden models are any models returned by the API that are not already part of
+ * the public hardcoded list. If the API key is missing or the request fails, an
+ * empty array is returned silently.
+ */
+export async function loadHiddenModels(
+  authStorage: AuthStorage,
+): Promise<ProviderModelConfig[]> {
+  const apiKey = await getNeuralwattApiKey(authStorage);
+  if (!apiKey) return [];
+
+  const result = await fetchNeuralwattModels(apiKey);
+  if (!result.success) return [];
+
+  const publicIds = new Set(NEURALWATT_MODELS.map((model) => model.id));
+
+  return result.data
+    .filter(
+      (model) =>
+        !model.metadata?.deprecated && !model.metadata?.pricing.pricing_tbd,
+    )
+    .filter((model) => !publicIds.has(model.id))
+    .map(buildHiddenModel);
+}

package/src/extensions/provider/models/index.ts

@@ -0,0 +1,23 @@
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import { buildLegacyNeuralwattModels } from "./legacy";
+import { NEURALWATT_MODELS } from "./public-models";
+
+export { loadHiddenModels } from "./hidden";
+export {
+  buildLegacyNeuralwattModels,
+  LEGACY_MODEL_ALIAS_MAP,
+  LEGACY_NEURALWATT_MODEL_IDS,
+} from "./legacy";
+export { NEURALWATT_MODELS } from "./public-models";
+
+export function getNeuralwattModels(options?: {
+  includeLegacyModelIds?: boolean;
+}): ProviderModelConfig[] {
+  const models: ProviderModelConfig[] = [...NEURALWATT_MODELS];
+
+  if (options?.includeLegacyModelIds) {
+    models.push(...buildLegacyNeuralwattModels());
+  }
+
+  return models;
+}

package/src/extensions/provider/models/legacy.ts

@@ -0,0 +1,37 @@
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import { NEURALWATT_MODELS } from "./public-models";
+
+// Legacy model IDs that should resolve to a canonical public model.
+// These are phased out over time and are only included when `includeLegacyModelIds` is enabled.
+export const LEGACY_MODEL_ALIAS_MAP = {
+  "glm-5.1": "glm-5.2",
+  "glm-5.1-fast": "glm-5.2-fast",
+  "zai-org/GLM-5.1-FP8": "glm-5.2",
+  "moonshotai/Kimi-K2.6": "kimi-k2.6",
+  "Qwen/Qwen3.5-397B-A17B-FP8": "qwen3.5-397b",
+  "Qwen/Qwen3.6-35B-A3B": "qwen3.6-35b",
+} as const;
+
+export const LEGACY_NEURALWATT_MODEL_IDS = new Set<string>(
+  Object.keys(LEGACY_MODEL_ALIAS_MAP),
+);
+
+export function buildLegacyNeuralwattModels(): ProviderModelConfig[] {
+  return Object.entries(LEGACY_MODEL_ALIAS_MAP).map(
+    ([legacyId, canonicalId]) => {
+      const canonical = NEURALWATT_MODELS.find(
+        (model) => model.id === canonicalId,
+      );
+
+      if (!canonical) {
+        throw new Error(`Missing canonical model for legacy alias ${legacyId}`);
+      }
+
+      return {
+        ...canonical,
+        id: legacyId,
+        name: `${canonical.name} (legacy ID)`,
+      };
+    },
+  );
+}

package/src/extensions/provider/{models.ts → models/public-models.ts}

@@ -1,49 +1,28 @@
-// Hardcoded models from Neuralwatt API
-// Source: https://api.neuralwatt.com/v1/models
-// Pricing, capabilities, and limits from metadata fields in /v1/models
-
 import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
 
+// Public models returned by https://api.neuralwatt.com/v1/models (unauthenticated view).
+// Pricing, capabilities, and limits are sourced from the API metadata fields.
 export const NEURALWATT_MODELS: ProviderModelConfig[] = [
-  // GLM-5 Fast - ZhipuAI
-  {
-    id: "glm-5-fast",
-    name: "GLM-5 Fast",
-    reasoning: false,
-    input: ["text"],
-    cost: {
-      input: 1.1,
-      output: 3.6,
-      cacheRead: 0,
-      cacheWrite: 0,
-    },
-    contextWindow: 202736,
-    maxTokens: 65536,
-    compat: {
-      supportsDeveloperRole: false,
-      maxTokensField: "max_tokens",
-    },
-  },
-  // GLM-5.1 - ZhipuAI
+  // GLM-5.2 - ZhipuAI
   {
-    id: "glm-5.1",
-    name: "GLM-5.1",
+    id: "glm-5.2",
+    name: "GLM-5.2",
     reasoning: true,
     input: ["text"],
     cost: {
-      input: 1.1,
-      output: 3.6,
-      cacheRead: 0,
+      input: 1.45,
+      output: 4.5,
+      cacheRead: 0.3625,
       cacheWrite: 0,
     },
-    contextWindow: 202736,
+    contextWindow: 1048560,
     maxTokens: 65536,
     thinkingLevelMap: {
       minimal: null,
       low: null,
-      medium: "medium",
-      high: null,
-      xhigh: null,
+      medium: null,
+      high: "high",
+      xhigh: "max",
     },
     compat: {
       supportsDeveloperRole: false,
@@ -51,53 +30,23 @@ export const NEURALWATT_MODELS: ProviderModelConfig[] = [
       requiresReasoningContentOnAssistantMessages: true,
     },
   },
-  // GLM-5.1 Fast - ZhipuAI
+  // GLM-5.2 Fast - ZhipuAI
   {
-    id: "glm-5.1-fast",
-    name: "GLM-5.1 Fast",
+    id: "glm-5.2-fast",
+    name: "GLM-5.2 Fast",
     reasoning: false,
     input: ["text"],
-    cost: {
-      input: 1.1,
-      output: 3.6,
-      cacheRead: 0,
-      cacheWrite: 0,
-    },
-    contextWindow: 202736,
-    maxTokens: 65536,
-    compat: {
-      supportsDeveloperRole: false,
-      maxTokensField: "max_tokens",
-    },
-  },
-  // GLM-5.2 - ZhipuAI (test canary)
-  {
-    id: "glm-5.2",
-    name: "GLM-5.2",
-    reasoning: true,
-    input: ["text"],
     cost: {
       input: 1.45,
       output: 4.5,
-      cacheRead: 0,
+      cacheRead: 0.3625,
       cacheWrite: 0,
     },
     contextWindow: 1048560,
     maxTokens: 65536,
-    // GLM-5.2 has two native reasoning depths (high, max) plus thinking-off.
-    // Pi levels below high disable thinking; high -> high, xhigh -> max.
-    // See https://portal.neuralwatt.com/docs/api/chat-completions#reasoning-effort
-    thinkingLevelMap: {
-      minimal: null,
-      low: null,
-      medium: null,
-      high: "high",
-      xhigh: "max",
-    },
     compat: {
       supportsDeveloperRole: false,
       maxTokensField: "max_tokens",
-      requiresReasoningContentOnAssistantMessages: true,
     },
   },
   // Kimi K2.5 - MoonshotAI
@@ -109,7 +58,7 @@ export const NEURALWATT_MODELS: ProviderModelConfig[] = [
     cost: {
       input: 0.52,
       output: 2.59,
-      cacheRead: 0,
+      cacheRead: 0.13,
       cacheWrite: 0,
     },
     contextWindow: 262128,
@@ -136,7 +85,7 @@ export const NEURALWATT_MODELS: ProviderModelConfig[] = [
     cost: {
       input: 0.52,
       output: 2.59,
-      cacheRead: 0,
+      cacheRead: 0.13,
       cacheWrite: 0,
     },
     contextWindow: 262128,
@@ -155,7 +104,7 @@ export const NEURALWATT_MODELS: ProviderModelConfig[] = [
     cost: {
       input: 0.69,
       output: 3.22,
-      cacheRead: 0,
+      cacheRead: 0.1725,
       cacheWrite: 0,
     },
     contextWindow: 262128,
@@ -182,7 +131,7 @@ export const NEURALWATT_MODELS: ProviderModelConfig[] = [
     cost: {
       input: 0.69,
       output: 3.22,
-      cacheRead: 0,
+      cacheRead: 0.1725,
       cacheWrite: 0,
     },
     contextWindow: 262128,
@@ -201,7 +150,7 @@ export const NEURALWATT_MODELS: ProviderModelConfig[] = [
     cost: {
       input: 0.69,
       output: 4.14,
-      cacheRead: 0,
+      cacheRead: 0.1725,
       cacheWrite: 0,
     },
     contextWindow: 262128,
@@ -228,7 +177,7 @@ export const NEURALWATT_MODELS: ProviderModelConfig[] = [
     cost: {
       input: 0.69,
       output: 4.14,
-      cacheRead: 0,
+      cacheRead: 0.1725,
       cacheWrite: 0,
     },
     contextWindow: 262128,
@@ -247,7 +196,7 @@ export const NEURALWATT_MODELS: ProviderModelConfig[] = [
     cost: {
       input: 0.29,
       output: 1.15,
-      cacheRead: 0,
+      cacheRead: 0.0725,
       cacheWrite: 0,
     },
     contextWindow: 131056,
@@ -274,7 +223,7 @@ export const NEURALWATT_MODELS: ProviderModelConfig[] = [
     cost: {
       input: 0.95,
       output: 4.0,
-      cacheRead: 0,
+      cacheRead: 0.2375,
       cacheWrite: 0,
     },
     contextWindow: 262128,
@@ -302,7 +251,7 @@ export const NEURALWATT_MODELS: ProviderModelConfig[] = [
     cost: {
       input: 0.29,
       output: 1.15,
-      cacheRead: 0,
+      cacheRead: 0.0725,
       cacheWrite: 0,
     },
     contextWindow: 131056,
@@ -313,39 +262,3 @@ export const NEURALWATT_MODELS: ProviderModelConfig[] = [
     },
   },
 ];
-
-const LEGACY_MODEL_ALIAS_MAP = {
-  "zai-org/GLM-5.1-FP8": "glm-5.1",
-  "moonshotai/Kimi-K2.6": "kimi-k2.6",
-  "Qwen/Qwen3.5-397B-A17B-FP8": "qwen3.5-397b",
-  "Qwen/Qwen3.6-35B-A3B": "qwen3.6-35b",
-} as const;
-
-export const LEGACY_NEURALWATT_MODEL_IDS = new Set<string>(
-  Object.keys(LEGACY_MODEL_ALIAS_MAP),
-);
-
-const LEGACY_NEURALWATT_MODELS: ProviderModelConfig[] = Object.entries(
-  LEGACY_MODEL_ALIAS_MAP,
-).map(([legacyId, canonicalId]) => {
-  const canonical = NEURALWATT_MODELS.find((model) => model.id === canonicalId);
-
-  if (!canonical) {
-    throw new Error(`Missing canonical model for legacy alias ${legacyId}`);
-  }
-
-  return {
-    ...canonical,
-    id: legacyId,
-    name: `${canonical.name} (legacy ID)`,
-  };
-});
-
-export function getNeuralwattModels(options?: {
-  includeLegacyModelIds?: boolean;
-}): ProviderModelConfig[] {
-  if (options?.includeLegacyModelIds)
-    return [...NEURALWATT_MODELS, ...LEGACY_NEURALWATT_MODELS];
-
-  return NEURALWATT_MODELS;
-}

package/src/extensions/provider/quota-store.ts

@@ -1,8 +1,8 @@
 import type { AuthStorage } from "@earendil-works/pi-coding-agent";
 import { getNeuralwattApiKey } from "../../lib/env";
+import { fetchQuotas } from "../../lib/neuralwatt-api";
 import type { NeuralwattQuotas } from "../../types/quota-api";
 import { parseQuotaHeaders } from "../../types/quota-events";
-import { fetchQuotas } from "../../utils/quotas";
 
 export function buildQuotasFromHeaders(
   headers: Record<string, string>,

package/src/extensions/provider/rate-limit-error.ts

@@ -0,0 +1,150 @@
+interface AssistantErrorLike {
+  role: string;
+  stopReason?: string;
+  provider?: string;
+  errorMessage?: string;
+}
+
+/**
+ * Parsed rate-limit info from Neuralwatt 429 response headers.
+ *
+ * Neuralwatt applies three independent rate-limit layers plus a legacy RPM
+ * layer. Each sets unique headers so the client can tell which layer
+ * triggered the rejection.
+ *
+ * @see https://portal.neuralwatt.com/docs/guides/rate-limits
+ */
+export interface NeuralwattRateLimitInfo {
+  /** Which rate-limit layer triggered the 429 */
+  layer: "concurrent" | "tpm" | "admission" | "rpm" | "unknown";
+  /** Seconds the server recommends waiting before retrying */
+  retryAfter?: number;
+  /** Human-readable details (varies per layer) */
+  detail: string;
+}
+
+/** Case-insensitive header lookup */
+function getHeader(
+  headers: Record<string, string>,
+  name: string,
+): string | undefined {
+  const entry = Object.entries(headers).find(
+    ([key]) => key.toLowerCase() === name.toLowerCase(),
+  );
+  return entry?.[1];
+}
+
+/**
+ * Parse Neuralwatt rate-limit headers from a 429 response.
+ *
+ * Returns `undefined` if no rate-limit-specific headers are found (e.g. the
+ * 429 came from a different proxy or middleware that doesn't set these
+ * headers).
+ */
+export function parseRateLimitHeaders(
+  headers: Record<string, string>,
+): NeuralwattRateLimitInfo | undefined {
+  const retryAfterRaw = getHeader(headers, "Retry-After");
+  const retryAfter = retryAfterRaw
+    ? Number.parseInt(retryAfterRaw, 10)
+    : undefined;
+
+  // 1. Concurrent-request limit
+  const concurrentDimension = getHeader(
+    headers,
+    "X-Concurrent-Limit-Dimension",
+  );
+  if (concurrentDimension) {
+    const active = getHeader(headers, "X-Concurrent-Limit-Active") ?? "?";
+    const max = getHeader(headers, "X-Concurrent-Limit-Max") ?? "?";
+    return {
+      layer: "concurrent",
+      retryAfter,
+      detail: `Concurrent request limit reached (${active}/${max} active, ${concurrentDimension}-scoped). Wait for an in-flight request to complete before retrying.`,
+    };
+  }
+
+  // 2. Input TPM limit
+  const tpmDimension = getHeader(headers, "X-TPM-Limit-Dimension");
+  if (tpmDimension) {
+    const tokens = getHeader(headers, "X-TPM-Limit-Tokens") ?? "?";
+    const max = getHeader(headers, "X-TPM-Limit-Max") ?? "?";
+    return {
+      layer: "tpm",
+      retryAfter,
+      detail: `Input token rate exceeded (${tokens}/${max} tokens/min, ${tpmDimension}-scoped). Wait before sending more requests.`,
+    };
+  }
+
+  // 3. Admission control
+  const admissionDimension = getHeader(headers, "X-Admission-Dimension");
+  if (admissionDimension) {
+    const inFlight = getHeader(headers, "X-Admission-InFlight") ?? "?";
+    const threshold = getHeader(headers, "X-Admission-Threshold") ?? "?";
+    return {
+      layer: "admission",
+      retryAfter,
+      detail: `Backend at capacity (${inFlight}/${threshold} in-flight tokens, ${admissionDimension}-scoped). The server is busy — retry shortly.`,
+    };
+  }
+
+  // 4. Legacy RPM limit
+  const rpmLimit = getHeader(headers, "X-RateLimit-Limit");
+  if (rpmLimit) {
+    const remaining = getHeader(headers, "X-RateLimit-Remaining") ?? "?";
+    return {
+      layer: "rpm",
+      retryAfter,
+      detail: `Requests per minute exceeded (${remaining}/${rpmLimit} remaining). Wait before sending more requests.`,
+    };
+  }
+
+  // Generic 429 with Retry-After but no layer-specific headers
+  if (retryAfter !== undefined) {
+    return {
+      layer: "unknown",
+      retryAfter,
+      detail: "Rate limited by the server. Wait before retrying.",
+    };
+  }
+
+  return undefined;
+}
+
+/**
+ * Build a user-facing error message from a NeuralwattRateLimitInfo.
+ */
+function formatRateLimitError(info: NeuralwattRateLimitInfo): string {
+  const parts = [info.detail];
+
+  if (info.retryAfter !== undefined && info.retryAfter > 0) {
+    if (info.retryAfter < 60) {
+      parts.push(`Retry-After: ${info.retryAfter}s.`);
+    } else {
+      const mins = Math.ceil(info.retryAfter / 60);
+      parts.push(`Retry-After: ~${mins} min.`);
+    }
+  } else if (info.retryAfter === 0 && info.layer === "concurrent") {
+    // Retry-After: 0 means: retry as soon as a slot frees
+    parts.push("Retry immediately after an in-flight request completes.");
+  }
+
+  return `429 rate limit: ${parts.join(" ")}`;
+}
+
+/**
+ * Normalize Neuralwatt rate-limit errors so the user sees which layer
+ * triggered the 429 and what to do about it.
+ *
+ * Without this, Pi shows a generic "Too Many Requests" because the
+ * Neuralwatt 429 response body is empty — all diagnostics are in the
+ * response headers.
+ */
+export function normalizeNeuralwattRateLimitError<
+  TMessage extends AssistantErrorLike,
+>(message: TMessage, rateLimitInfo: NeuralwattRateLimitInfo): TMessage {
+  return {
+    ...message,
+    errorMessage: formatRateLimitError(rateLimitInfo),
+  };
+}

package/src/extensions/provider/sse-quotas.ts

@@ -0,0 +1,84 @@
+import type { NeuralwattQuotas } from "../../types/quota-api";
+
+const JOULES_PER_KWH = 3_600_000;
+
+export function updateQuotasFromSseComment(
+  quotas: NeuralwattQuotas | undefined,
+  line: string,
+): NeuralwattQuotas | undefined {
+  if (!quotas) return;
+  const trimmed = line.trim();
+  const next = structuredClone(quotas);
+
+  try {
+    if (trimmed.startsWith(": energy ")) {
+      const energy = JSON.parse(trimmed.slice(9)) as { energy_joules?: number };
+      const energyKwh = (energy.energy_joules ?? 0) / JOULES_PER_KWH;
+      if (energyKwh <= 0) return quotas;
+      next.usage.current_month.energy_kwh += energyKwh;
+      next.usage.lifetime.energy_kwh += energyKwh;
+      if (next.subscription) {
+        next.subscription.kwh_used += energyKwh;
+        next.subscription.kwh_remaining = Math.max(
+          0,
+          next.subscription.kwh_remaining - energyKwh,
+        );
+      }
+      next.snapshot_at = new Date().toISOString();
+      return next;
+    }
+
+    if (trimmed.startsWith(": cost ")) {
+      const cost = JSON.parse(trimmed.slice(7)) as {
+        request_cost_usd?: number;
+      };
+      const requestCostUsd = cost.request_cost_usd ?? 0;
+      if (requestCostUsd <= 0) return quotas;
+      next.balance.credits_remaining_usd = Math.max(
+        0,
+        next.balance.credits_remaining_usd - requestCostUsd,
+      );
+      next.balance.credits_used_usd += requestCostUsd;
+      next.usage.current_month.cost_usd += requestCostUsd;
+      next.usage.lifetime.cost_usd += requestCostUsd;
+      next.snapshot_at = new Date().toISOString();
+      return next;
+    }
+  } catch {
+    return quotas;
+  }
+
+  return quotas;
+}
+
+export async function readQuotaCommentsFromTee(
+  body: ReadableStream<Uint8Array>,
+  onComment: (line: string) => void,
+): Promise<void> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) onComment(line);
+    }
+
+    const final = decoder.decode(new Uint8Array(0), { stream: false });
+    const remaining = (buffer + final).trim();
+    if (remaining) onComment(remaining);
+  } catch {
+    // The SDK side may abort the tee; quota comments are best-effort.
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      // ignore
+    }
+  }
+}

package/src/extensions/provider/stream-simple.ts

@@ -0,0 +1,138 @@
+// Neuralwatt is OpenAI-compatible, but the OpenAI SDK throws on non-2xx
+// responses before Pi's after_provider_response hook can see the raw headers.
+// We wrap the built-in openai-completions streamSimple so 429 rate-limit
+// headers can be captured before the SDK turns them into a generic error, while
+// still delegating normal streaming behavior to Pi's provider implementation.
+//
+// The SSE tee used for live quota comments is inspired by:
+// https://github.com/monotykamary/pi-neuralwatt-provider
+
+import {
+  type AssistantMessageEventStream,
+  type Context,
+  createAssistantMessageEventStream,
+  type Model,
+  type SimpleStreamOptions,
+} from "@earendil-works/pi-ai";
+import {
+  type NeuralwattRateLimitInfo,
+  normalizeNeuralwattRateLimitError,
+  parseRateLimitHeaders,
+} from "./rate-limit-error";
+import { readQuotaCommentsFromTee } from "./sse-quotas";
+
+export type AnyStreamSimple = (
+  model: Model<string>,
+  context: Context,
+  options?: SimpleStreamOptions,
+) => AssistantMessageEventStream;
+
+function headersToRecord(headers: Headers): Record<string, string> {
+  const record: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    record[key] = value;
+  });
+  return record;
+}
+
+function isProviderChatCompletionsUrl(
+  input: RequestInfo | URL,
+  providerOrigin: string,
+): boolean {
+  const rawUrl =
+    typeof input === "string"
+      ? input
+      : input instanceof URL
+        ? input.toString()
+        : input.url;
+
+  try {
+    const url = new URL(rawUrl);
+    return (
+      url.origin === providerOrigin &&
+      url.pathname.endsWith("/chat/completions")
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function forwardStream(
+  stream: AssistantMessageEventStream,
+  outer: AssistantMessageEventStream,
+  getRateLimitInfo: () => NeuralwattRateLimitInfo | undefined,
+  restoreFetch: () => void,
+): Promise<void> {
+  try {
+    for await (const event of stream) {
+      const rateLimitInfo = getRateLimitInfo();
+      if (event.type === "error" && rateLimitInfo) {
+        outer.push({
+          ...event,
+          error: normalizeNeuralwattRateLimitError(event.error, rateLimitInfo),
+        });
+      } else {
+        outer.push(event);
+      }
+    }
+  } finally {
+    restoreFetch();
+    outer.end();
+  }
+}
+
+export function wrapNeuralwattStreamSimple(
+  base: AnyStreamSimple,
+  onSseQuota: (line: string) => void,
+): AnyStreamSimple {
+  return (model, context, options = {}) => {
+    let rateLimitInfo: NeuralwattRateLimitInfo | undefined;
+    let sseQuotaTask: Promise<void> | undefined;
+    const outer = createAssistantMessageEventStream();
+    const providerOrigin = new URL(
+      model.baseUrl ?? "https://api.neuralwatt.com/v1",
+    ).origin;
+    const originalFetch = globalThis.fetch;
+    const wrappedFetch: typeof fetch = async (input, init) => {
+      const response = await originalFetch(input, init);
+
+      if (!isProviderChatCompletionsUrl(input, providerOrigin)) return response;
+
+      const headers = headersToRecord(response.headers);
+      if (response.status === 429) {
+        rateLimitInfo = parseRateLimitHeaders(headers);
+        return response;
+      }
+
+      if (response.ok && response.body) {
+        const [sdkBody, quotaBody] = response.body.tee();
+        sseQuotaTask = readQuotaCommentsFromTee(quotaBody, onSseQuota);
+        return new Response(sdkBody, {
+          headers: response.headers,
+          status: response.status,
+          statusText: response.statusText,
+        });
+      }
+
+      return response;
+    };
+
+    globalThis.fetch = wrappedFetch;
+
+    const restoreFetch = () => {
+      if (globalThis.fetch === wrappedFetch) globalThis.fetch = originalFetch;
+      sseQuotaTask?.catch(() => {});
+    };
+
+    const stream = base(model, context, options);
+    const originalOuterEnd = outer.end.bind(outer);
+    outer.end = (result?: Parameters<typeof originalOuterEnd>[0]) => {
+      restoreFetch();
+      originalOuterEnd(result);
+    };
+
+    void forwardStream(stream, outer, () => rateLimitInfo, restoreFetch);
+
+    return outer;
+  };
+}

package/src/{utils/quotas.ts → lib/neuralwatt-api.ts}

@@ -1,6 +1,11 @@
+import type {
+  NeuralwattApiModel,
+  NeuralwattApiModelsResponse,
+} from "../types/models-api";
 import type { NeuralwattQuotas } from "../types/quota-api";
 import type { QuotasResult } from "../types/quota-events";
 
+const BASE_URL = "https://api.neuralwatt.com/v1";
 const FETCH_TIMEOUT_MS = 15_000;
 
 function isTimeoutReason(reason: unknown): boolean {
@@ -10,6 +15,55 @@ function isTimeoutReason(reason: unknown): boolean {
   );
 }
 
+function combineSignals(signal?: AbortSignal): AbortSignal {
+  const signals: AbortSignal[] = [AbortSignal.timeout(FETCH_TIMEOUT_MS)];
+  if (signal) signals.push(signal);
+  return AbortSignal.any(signals);
+}
+
+async function neuralwattFetch(
+  path: string,
+  apiKey: string,
+  signal?: AbortSignal,
+  headers?: Record<string, string>,
+): Promise<Response> {
+  return fetch(`${BASE_URL}${path}`, {
+    headers: { Authorization: `Bearer ${apiKey}`, ...headers },
+    signal: combineSignals(signal),
+  });
+}
+
+export type NeuralwattModelsResult =
+  | { success: true; data: NeuralwattApiModel[] }
+  | { success: false };
+
+export async function fetchNeuralwattModels(
+  apiKey: string,
+  signal?: AbortSignal,
+): Promise<NeuralwattModelsResult> {
+  if (!apiKey) {
+    return { success: false };
+  }
+
+  const combined = combineSignals(signal);
+
+  try {
+    const response = await neuralwattFetch("/models", apiKey, combined, {
+      Referer: "https://pi.dev",
+      "X-Title": "npm:@aliou/pi-neuralwatt",
+    });
+
+    if (!response.ok) {
+      return { success: false };
+    }
+
+    const data: NeuralwattApiModelsResponse = await response.json();
+    return { success: true, data: data.data };
+  } catch {
+    return { success: false };
+  }
+}
+
 export async function fetchQuotas(
   apiKey: string,
   signal?: AbortSignal,
@@ -21,15 +75,10 @@ export async function fetchQuotas(
     };
   }
 
-  const signals: AbortSignal[] = [AbortSignal.timeout(FETCH_TIMEOUT_MS)];
-  if (signal) signals.push(signal);
-  const combined = AbortSignal.any(signals);
+  const combined = combineSignals(signal);
 
   try {
-    const response = await fetch("https://api.neuralwatt.com/v1/quota", {
-      headers: { Authorization: `Bearer ${apiKey}` },
-      signal: combined,
-    });
+    const response = await neuralwattFetch("/quota", apiKey, combined);
 
     if (!response.ok) {
       let message = response.statusText;

package/src/types/models-api.ts

@@ -0,0 +1,53 @@
+export interface NeuralwattApiModelPricing {
+  input_per_million: number;
+  output_per_million: number;
+  cached_input_per_million: number | null;
+  cached_output_per_million: number | null;
+  currency: string;
+  pricing_tbd: boolean;
+}
+
+export interface NeuralwattApiModelCapabilities {
+  tools: boolean;
+  json_mode: boolean;
+  vision: boolean;
+  reasoning: boolean;
+  reasoning_effort: boolean;
+  streaming: boolean;
+  system_role: boolean;
+  developer_role: boolean;
+}
+
+export interface NeuralwattApiModelLimits {
+  max_context_length: number;
+  max_output_tokens: number | null;
+  max_images: number | null;
+}
+
+export interface NeuralwattApiModelMetadata {
+  display_name: string;
+  description: string | null;
+  provider: string;
+  huggingface_id: string | null;
+  pricing: NeuralwattApiModelPricing;
+  capabilities: NeuralwattApiModelCapabilities;
+  limits: NeuralwattApiModelLimits;
+  deprecated: boolean;
+  deprecated_message: string | null;
+}
+
+export interface NeuralwattApiModel {
+  id: string;
+  object: string;
+  created: number;
+  owned_by: string;
+  root?: string;
+  parent?: string | null;
+  max_model_len: number;
+  metadata?: NeuralwattApiModelMetadata;
+}
+
+export interface NeuralwattApiModelsResponse {
+  object: "list";
+  data: NeuralwattApiModel[];
+}

package/src/types/quota-events.ts

@@ -1,6 +1,6 @@
 import type { NeuralwattQuotas } from "./quota-api";
 
-export type QuotaSource = "header" | "api";
+export type QuotaSource = "header" | "api" | "sse";
 
 export const NEURALWATT_QUOTAS_UPDATED_EVENT =
   "neuralwatt:quotas:updated" as const;