@gtrabanco/pi-nan-provider 0.10.0 → 0.10.3

package/AGENTS.md

@@ -140,6 +140,24 @@ Every PR that changes code MUST bump `package.json` version in the same PR; CI p
   runtime then drives `fetchModels` refreshes (network refresh at interactive
   startup and periodically, cache-only at registration) and persists the overlay.
   A `fetchModels` rejection never blocks startup.
+- **pi 0.99 virtual models do not break the provider, but they do interact with the
+  cross-model thinking guard** (verified pi 0.99.1/0.99.2). A virtual model
+  (`pi.registerVirtualModel`, api `pi-virtual`) can be registered under `nan` and
+  route to physical `nan` models via `ctx.modelRegistry.find("nan", id)` — no
+  provider-side change needed. Inside the extension `context` hook, though,
+  `ctx.model` is the **selection** (the virtual entry), never the routed physical
+  model (`core/virtual-models.js`; `agent-session.js` "The selection stays in
+  agent state; only this request uses the routed model"), and the routed target is
+  not exposed to the hook. `stripCrossModelThinking` therefore skips virtual
+  selections (`src/cross-model-thinking-guard.ts`, `VIRTUAL_MODEL_API`); otherwise
+  its same-model check would strip reasoning on every continuation. Registered
+  virtual models are otherwise transparent to the catalog/factory.
+- **Factory-time ExtensionAPI has NO `modelRegistry`** (verified pi 0.99.1):
+  The `ExtensionAPI` interface does not include `modelRegistry`; it exists only on
+  `ExtensionContext` (the `ctx` passed to command/event handlers). At factory time,
+  stored credentials are resolved via `readStoredCredential("nan")` from
+  `@earendil-works/pi-coding-agent`. Command-time paths (`/nan-mcp`, `/nan-usage`) use
+  `ctx.modelRegistry`.
 - models.json overrides compose **above** registered native providers.
 - Capability values that diverge from models.dev are recorded as build-time
   `MANUAL_OVERRIDES` (mandatory provenance note) in `scripts/manual-overrides.ts`,
@@ -180,9 +198,16 @@ Every PR that changes code MUST bump `package.json` version in the same PR; CI p
   entry) so the id is never emitted twice.
   Non-chat endpoints: qwen3-embedding, rerank, kokoro (TTS), whisper (STT),
   flux-2-klein and qwen-image-2.1 (images) — MCP-bridge territory, not chat
-  catalog models; `qwen-image-2.1` also sits on models.dev with
-  `limit.output: 0`, so generation excludes it via `NON_CHAT_MODEL_IDS`
-  instead of flagging it "needs manual verification" forever.
+  catalog models. The classification is now applied at RUNTIME too:
+  `NON_CHAT_MODEL_IDS` is exported from `src/fetch-models.ts` (single source
+  of truth: id → provenance reason), imported by `scripts/generate-models.ts`
+  (one definition, no duplicate), enforced by `mergeLiveWithGenerated` (those
+  ids land in the `nonChat` bucket and never enter the registry), and filtered
+  defensively by `baselineModels`. The generator excluded `qwen-image-2.1` via
+  this constant before (it also sits on models.dev with `limit.output: 0`,
+  excluded instead of being flagged "needs manual verification" forever); all
+  six ids are now under the same guard so they can never be emitted as chat
+  models or registered at runtime.
 - NaN can close an SSE stream **before** `finish_reason`. The catalog sets
   `supportsFinishReason: true` so pi-ai raises the retryable
   `Stream ended without finish_reason` (pi-ai's `RETRYABLE_PROVIDER_ERROR_PATTERN`
@@ -202,6 +227,7 @@ Every PR that changes code MUST bump `package.json` version in the same PR; CI p
   `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.
+- **Catalog now declares `thinkingLevelMap` for reasoning suppression** (issue #16, measured 2026-09-27 against live gateway, repro script in the issue). `deepseek-v4-flash` → `{ off: "none" }` (0 reasoning tokens, reproducible); `glm5.3-flash` → `{ off: "minimal" }` (38 reasoning tokens + answer; `none` does NOT work on glm5.3 — 13,382 tokens); `qwen3.6` and `gemma4` → `{ off: "none" }` (gap left by the measured-only fix: the NaN docs state that with no parameter both reason by default with a 16,384-token budget and that `none`/`minimal` skip the reasoning phase entirely — https://nan.builders/docs/models#controlling-reasoning, checked 2026-10-01 — so `off` must send `none` explicitly). `reasoningEffortValues` corrected: deepseek-v4-flash from `[]` to `["none"]`; glm5.3-flash from `["low","medium","high","max"]` to include `"minimal"`. README limits table notes that `maxTokens` does NOT bound the reasoning phase (measured: max_tokens=512 still yielded 13,376 reasoning tokens). pi-ai's `buildRequest` (0.99.1) maps `reasoning: "off"` → `reasoningEffort: undefined` → fires the off-branch that checks `model.thinkingLevelMap?.off` (verified in pi-ai source ~line 718-722). A model whose reasoning depth is genuinely not adjustable (`qwen3.8-flash`, `mimo-v2.6-flash`) keeps no `thinkingLevelMap`: `off` sends nothing and the model uses its own default.
 - 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
@@ -241,3 +267,18 @@ Every PR that changes code MUST bump `package.json` version in the same PR; CI p
   - Automated check (scripts/check-nan-mcp-server.ts) compares the npm registry
     against the pin weekly and files a `dependencies` issue when a newer release
     exists, with a breaking/safe verdict from the live server tool surface.
+- **pi reports unhandled MCP registrations right after `session_start`** (verified
+  on pi 0.99.1): `AgentSession.bindExtensions()` emits `session_start` and then
+  calls `ExtensionRunner.reportUnhandledMcpServers()`, which raises
+  `MCP server "<name>" is registered, but no loaded extension connects MCP
+  servers` whenever no loaded extension handles `mcp_servers_change`. A host
+  that builds `DefaultResourceLoader` WITHOUT `extensionFactories` loads no
+  `builtin:*` extension at all — PI WEB's `createAgentSessionServices` does
+  exactly that (pi-web 1.202609.1, verified 2026-09-30 with a faithful loader
+  run: packages load, `builtin:mcp` absent, no `/mcp` command), so its sessions
+  have no MCP connector and `mcp.json` servers never connect either.
+  `src/mcp/host-support.ts` detects the gap through the `/mcp` command
+  (`pi.getCommands()` missing → conservative "connector present"), claims
+  `mcp_servers_change` so pi's report stays silent, and warns once per session;
+  `/nan-mcp enable` persists the toggle without registering. Regression tests:
+  `test/mcp-host-connector.test.ts`.

package/README.es.md

@@ -41,6 +41,8 @@ El proveedor utiliza un **catálogo de modelos de dos capas** para garantizar la
 > [!IMPORTANT]
 > **Detección de Tier**: La lista en vivo es la autoridad. Si tu clave tiene acceso premium, esos modelos aparecerán automáticamente; de lo contrario, se filtran.
 
+Los ids no-chat que devuelve `/models` en vivo (embedding, rerank, TTS, STT, imagen) **no se registran** como modelos de chat — la clasificación es el único `NON_CHAT_MODEL_IDS` exportado desde `src/fetch-models.ts` (la misma fuente que usa el generador en build-time). La fusión salta sus marcadores y los coloca en un bucket observable `nonChat`; `baselineModels` también los filtra como capa defensiva. Esto evita que el selector de chat de pi ofrezca endpoints que no pueden servir chat (las peticiones devolverían 404).
+
 El registro es síncrono a propósito: el catálogo de fallback está disponible al instante, y el runtime de Models de pi dirige el refresco en vivo (refresco de red en el arranque interactivo y periódico, solo caché en el registro), persistiendo el overlay entre ejecuciones.
 
 ### 🧠 Seguridad al cambiar de modelo (guard de razonamiento cross-model)
@@ -107,10 +109,42 @@ Ambos puentes están **activados por defecto** (por sesión, visibles en `/mcp`)
 
 | Comando | Efecto |
 | :--- | :--- |
-| `/nan-mcp status` | Muestra el estado actual de ambos puentes. |
+| `/nan-mcp status` | Muestra el estado actual de ambos puentes y la resolución de la clave API. |
 | `/nan-mcp enable [target]` | Activa `web-search` o `nan-mcp-server` (persiste). |
 | `/nan-mcp disable [target]` | Desactiva un puente de forma persistente. |
 
+Ambos puentes resuelven la credencial almacenada de `/login nan` (almacenada → env). Si ninguna se resuelve, el puente no se registra y se muestra un aviso en la salida de estado.
+
+> [!NOTE]
+> El registro ocurre cuando se carga la extensión. Si ejecutas `/login nan` **después** de que la sesión haya empezado, la factoría ya se ejecutó — usa `/reload` (o `/nan-mcp enable`) para registrar los puentes sin reiniciar pi.
+
+### 🚧 Hosts sin la extensión MCP integrada de pi (PI WEB)
+
+pi conecta los servidores registrados desde la extensión que maneja `mcp_servers_change` — la
+extensión integrada `mcp`, que además registra `/mcp`. Los hosts que construyen el resource loader
+de pi sin `extensionFactories` no cargan **ninguna** extensión integrada (verificado:
+`createAgentSessionServices` de PI WEB, pi 0.99.1 / pi-web 1.202609.1), así que nada conecta los
+servidores y pi reporta `MCP server "nan-media" is registered, but no loaded extension connects MCP
+servers`.
+
+Ahí los puentes no pueden exponer herramientas, así que este paquete reemplaza ese error críptico
+con un único aviso por sesión, mantiene los registros inactivos y deja que `/nan-mcp enable` persista
+el toggle sin registrar un servidor que nunca podrá conectarse. Para tener MCP en la CLI, activa el
+conector con `pi config` → Built-in extensions → `mcp`.
+
+### Funciones de pi 0.99 y modelos NaN
+
+- **Modelos virtuales** — registra un router bajo `nan` (`pi.registerVirtualModel({ provider: "nan", ... })`);
+  enruta a los modelos físicos de NaN sin configuración por parte del proveedor. El guard de
+  razonamiento entre modelos se salta las selecciones virtuales, porque el modelo físico enrutado no
+  es visible para el hook `context`.
+- **Codemode** — funciona con cualquier modelo NaN que soporte tool calling. Las herramientas MCP de
+  este paquete usan `exposure: "direct"`, así que los scripts de codemode también pueden llamarlas.
+  Requiere la extensión integrada `codemode` de pi (ver la nota de PI WEB arriba).
+- **Modelos clasificadores** — no aplica: NaN no expone ninguna API de clasificación (solo chat y
+  endpoints de embedding/rerank/audio/imagen), así que este proveedor no registra modelos
+  `type: "classifier"`.
+
 ---
 
 ### 1. Servidor MCP oficial de NaN
@@ -271,6 +305,22 @@ Catálogo base (verificado contra [docs de NaN](https://nan.builders/docs/models
 
 ---
 
+---
+
+## 🧠 Controles de razonamiento
+
+El parámetro `reasoning_effort` de NaN controla cuánto piensa el modelo antes de responder — pero el grado de control varía por modelo:
+
+| Modelo | Effort de razonamiento | Cómo funciona |
+| :--- | :--- | :--- |
+| `glm5.3`, `glm5.3-flash` | `minimal` · `low` · `medium` · `high` · `max` | Completamente controlable — valores más altos permiten al modelo razonar más; `minimal` produce ~38 tokens de razonamiento (issue #16, medido 2026-09-27); `none` NO suprime el razonamiento en glm5.3-flash (13,382 tokens) |
+| `qwen3.6`, `gemma4` | `none` · `minimal` · `low` · `medium` · `high` · `max` | `none`/`minimal` omiten el razonamiento por completo; otros valores limitan a 2K / 8K / 16K / 32K tokens. `thinking: "off"` envía `reasoning_effort: "none"` automáticamente vía el `thinkingLevelMap` del catálogo — los docs de NaN dicen que sin parámetro estos modelos razonan por defecto (presupuesto de 16,384 tokens), así que `off` debe ser explícito |
+| `deepseek-v4-flash` | `none` · `minimal` · `low` · `medium` · `high` · `max` (el catálogo declara ["none"]) | `none` deshabilita el razonamiento de forma fiable (0 tokens de razonamiento, medido 2026-09-27); cualquier otro valor deja 13-14K tokens de razonamiento y causa razonamiento descontrolado (finish_reason:"length" con CERO texto de respuesta) — el catálogo solo declara `none` porque el resto es ruido. `thinking: "off"` ahora envía `reasoning_effort: "none"` automáticamente vía el `thinkingLevelMap` del catálogo |
+| `qwen3.8-flash`, `mimo-v2.6-flash` | *(aceptado pero no ajustable)* | El parámetro es aceptado y nunca rechazado, pero el modelo gestiona su propia profundidad de razonamiento — nunca es un error enviar un valor que estos modelos no ajustan |
+
+> [!NOTE]  
+> `maxTokens` NO limita la fase de razonamiento en los modelos de NaN. La fase de razonamiento corre hasta completarse (o se trunca a ~60,000 caracteres para deepseek-v4-flash) independientemente de `maxTokens` — medido: `max_tokens=512` en deepseek-v4-flash aún consumió 13,376 tokens de completación, todos de razonamiento (26x el techo). Este es un comportamiento del gateway confirmado por el issue #16 (medido 2026-09-27).
+
 ## 🚀 Desarrollo
 
 ```bash

package/README.md

@@ -41,6 +41,8 @@ The provider uses a **two-layer model catalog** to ensure reliability:
 > [!IMPORTANT]
 > **Tier Detection**: The live list is authoritative. If your key has premium access, those models will appear automatically; otherwise, they are filtered out.
 
+NaN's live `/models` also returns non-chat endpoint ids (embedding, rerank, TTS, STT, image). These are **not registered** as chat models — the classification is the single exported `NON_CHAT_MODEL_IDS` from `src/fetch-models.ts` (the same source used by the build-time generator). The merge skips their placeholders and places them in an observable `nonChat` bucket; `baselineModels` also filters them defensively. This prevents pi's chat picker from offering endpoints that cannot serve chat (requests would 404).
+
 The registration is synchronous on purpose: the generated fallback catalog is available immediately, and pi's Models runtime drives the live refresh (network refresh at interactive startup and periodically, cache-only at registration), persisting the overlay between runs.
 
 ### 🧠 Model-switch safety (cross-model reasoning guard)
@@ -107,10 +109,39 @@ Both bridges are **enabled by default** (session-scoped, visible in `/mcp`). Use
 
 | Command | Effect |
 | :--- | :--- |
-| `/nan-mcp status` | Shows current state of both bridges. |
+| `/nan-mcp status` | Shows current state of both bridges and API key resolution. |
 | `/nan-mcp enable [target]` | Enables `web-search` or `nan-mcp-server` (persisted). |
 | `/nan-mcp disable [target]` | Disables a bridge persistently. |
 
+Both bridges resolve the stored `/login nan` credential (stored → env). If neither resolves, the bridge does not register and a warning is shown in the status output.
+
+> [!NOTE]
+> Registration happens when the extension loads. If you run `/login nan` **after** the session started, the factory has already run — run `/reload` (or `/nan-mcp enable`) to register the bridges without restarting pi.
+
+### 🚧 Hosts without pi's built-in MCP extension (PI WEB)
+
+pi connects registered servers from the extension that handles `mcp_servers_change` — the built-in
+`mcp` extension, which also registers `/mcp`. Hosts that build pi's resource loader without
+`extensionFactories` load **no** built-in extension at all (verified: PI WEB's
+`createAgentSessionServices`, pi 0.99.1 / pi-web 1.202609.1), so nothing connects the servers and pi
+reports `MCP server "nan-media" is registered, but no loaded extension connects MCP servers`.
+
+There the bridges cannot expose tools, so this package replaces that cryptic error with one warning
+per session, keeps the registrations idle, and lets `/nan-mcp enable` persist the toggle without
+registering a server that can never connect. To get MCP in the CLI, enable the connector with
+`pi config` → Built-in extensions → `mcp`.
+
+### pi 0.99 features and NaN models
+
+- **Virtual models** — register a router under `nan` (`pi.registerVirtualModel({ provider: "nan", ... })`);
+  it routes to the physical NaN models with no provider-side configuration. The cross-model thinking
+  guard skips virtual selections, because the routed physical model is not visible to the `context` hook.
+- **Codemode** — works with any tool-calling NaN model. This package's MCP tools use
+  `exposure: "direct"`, so codemode scripts can call them as well. Requires pi's built-in `codemode`
+  extension (see the PI WEB note above).
+- **Classifier models** — not applicable: NaN exposes no classifier API (chat plus
+  embedding/rerank/audio/image endpoints only), so this provider registers no `type: "classifier"` models.
+
 ---
 
 ### 1. Official NaN MCP Server
@@ -277,9 +308,13 @@ NaN's `reasoning_effort` parameter controls how much the model thinks before ans
 
 | Model | Reasoning effort | How it works |
 | :--- | :--- | :--- |
-| `glm5.3`, `glm5.3-flash` | `low` · `medium` · `high` · `max` | Fully controllable — higher values let the model reason longer |
-| `qwen3.6`, `gemma4` | `none` · `minimal` · `low` · `medium` · `high` · `max` | `none`/`minimal` skip reasoning entirely; others cap at 2K / 8K / 16K / 32K tokens |
-| `deepseek-v4-flash`, `qwen3.8-flash`, `mimo-v2.6-flash` | *(accepted but not adjustable)* | The parameter is accepted and never rejected, but the model manages its own reasoning depth — it is never an error to send a value these models don't adjust |
+| `glm5.3`, `glm5.3-flash` | `minimal` · `low` · `medium` · `high` · `max` | Fully controllable — higher values let the model reason longer; `minimal` yields ~38 reasoning tokens (issue #16, measured 2026-09-27); `none` does NOT suppress reasoning on glm5.3-flash (13,382 tokens) |
+| `qwen3.6`, `gemma4` | `none` · `minimal` · `low` · `medium` · `high` · `max` | `none`/`minimal` skip reasoning entirely; others cap at 2K / 8K / 16K / 32K tokens. `thinking: "off"` sends `reasoning_effort: "none"` automatically via the catalog's `thinkingLevelMap` — the NaN docs state that with no parameter these models reason by default (16,384-token budget), so off must be explicit |
+| `deepseek-v4-flash` | `none` · `minimal` · `low` · `medium` · `high` · `max` (catalog declares ["none"]) | `none` reliably disables reasoning (0 reasoning tokens, measured 2026-09-27); every other value leaves 13-14K reasoning tokens and causes runaway reasoning (finish_reason:"length" with ZERO answer text) — the catalog only declares `none` because the rest are useless. `thinking: "off"` now sends `reasoning_effort: "none"` automatically via the catalog's `thinkingLevelMap` |
+| `qwen3.8-flash`, `mimo-v2.6-flash` | *(accepted but not adjustable)* | The parameter is accepted and never rejected, but the model manages its own reasoning depth — it is never an error to send a value these models don't adjust |
+> [!NOTE]  
+> `maxTokens` does NOT bound the reasoning phase on NaN models. The reasoning phase runs to completion (or truncates at ~60,000 chars for deepseek-v4-flash) regardless of `maxTokens` — measured: `max_tokens=512` on deepseek-v4-flash still consumed 13,376 completion tokens, all reasoning (26x the ceiling). This is gateway behavior confirmed by issue #16 (measured 2026-09-27).
+
 
 ---
 

package/package.json

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

@@ -25,7 +25,8 @@
  *   MANUAL_ONLY entry — or this script exits non-zero.
  * - Any other models.dev entry missing `limit.context`/`limit.output` is
  *   skipped and flagged "needs manual verification" — never guessed. Entries
- *   that are not chat models are excluded via NON_CHAT_MODEL_IDS instead.
+ *   that are not chat models are excluded via NON_CHAT_MODEL_IDS instead
+ *   (defined in `src/fetch-models.ts` and also enforced at runtime).
  * - models.dev modalities are intersected with pi's supported input set
  *   ("text" | "image"); e.g. mimo-v2.6-flash's audio input is not
  *   representable in pi's Model type and is dropped from `input` (noted on
@@ -33,6 +34,7 @@
  */
 
 import type { GeneratedModelEntry } from "../src/fetch-models.ts";
+import { NON_CHAT_MODEL_IDS } from "../src/fetch-models.ts";
 import type { ManualModelOverride } from "./manual-overrides.ts";
 import {
 	MANUAL_OVERRIDES,
@@ -97,17 +99,10 @@ const PROVIDER_REMOVED_MODEL_IDS: Record<string, string> = {
 		"removed by NaN (checked 2026-09-29): zero mentions in https://nan.builders/docs/models and in the model param description of https://nan.builders/openapi.json, and models.dev provider nan dropped it as well — superseded by mimo-v2.6-flash; excluded so regeneration does not resurrect it",
 };
 
-/**
- * models.dev entries that are not chat models. They can never join a chat
- * catalog (their output is an image, and models.dev reports limit.output 0),
- * so they are excluded with the docs as the reason instead of being flagged
- * "needs manual verification" forever — that flag would suggest limits worth
- * confirming for a model this package must not serve as chat.
- */
-const NON_CHAT_MODEL_IDS: Record<string, string> = {
-	"qwen-image-2.1":
-		"image-generation model (text→image; output modality image) documented in https://nan.builders/docs/models and https://nan.builders/openapi.json (checked 2026-09-29) — not a chat model, out of the static chat catalog (models.dev reports limit.output 0)",
-};
+// NON_CHAT_MODEL_IDS (six non-chat endpoint ids) is imported from its single
+// source of truth, `src/fetch-models.ts`, where the runtime live merge applies
+// the same classification. Here it feeds convertModel's exclusion and the
+// exclusion-note list in GENERATED_CATALOG_META.notes.
 
 /**
  * Premium/tier-gated models that models.dev documents but that are deliberately
@@ -237,6 +232,7 @@ function buildManualOnlyModelEntry(
 			contextWindow: override?.contextWindow ?? 1_048_576,
 			maxTokens: override?.maxTokens ?? 131_072,
 			reasoningEffortValues,
+			...(override?.thinkingLevelMap ? { thinkingLevelMap: { ...override.thinkingLevelMap } } : {}),
 			compat: { ...NAN_COMPAT },
 			notes: [
 				NAN_COMPAT_NOTE,
@@ -300,6 +296,7 @@ function convertModel(modelId: string, m: ModelsDevModel): GeneratedModel | { sk
 			contextWindow: override?.contextWindow ?? contextWindow,
 			maxTokens: override?.maxTokens ?? maxTokens,
 			reasoningEffortValues,
+			...(override?.thinkingLevelMap ? { thinkingLevelMap: { ...override.thinkingLevelMap } } : {}),
 			compat: { ...NAN_COMPAT },
 			notes: [
 				NAN_COMPAT_NOTE,
@@ -344,6 +341,14 @@ async function main(): Promise<void> {
 	// so the manual data never disappears silently.
 	const entryById = new Map(entries.map((entry) => [entry.id, entry]));
 	for (const [modelId, detail] of Object.entries(MANUAL_ONLY_MODEL_IDS)) {
+		// Guard: a MANUAL_ONLY_MODEL_IDS entry must not be a non-chat id.
+		// (REQUIRED_MODEL_IDS can't land here: if a required id were non-chat,
+		// convertModel skips it and the existing missing-required fail already
+		// fires — but this guard is explicit for MANUAL_ONLY.)
+		const nonChatReason = NON_CHAT_MODEL_IDS[modelId];
+		if (nonChatReason) {
+			fail(`MANUAL_ONLY_MODEL_IDS id "${modelId}" is classified as non-chat (${nonChatReason}) — this is a contradictory repo configuration`);
+		}
 		const existing = entryById.get(modelId);
 		if (existing) {
 			const note = `manual-only: "${modelId}" skipped: models.dev provider "${SOURCE_PROVIDER_ID}" now lists it, so the manual-only entry is not emitted and the models.dev values are used (${detail})`;

package/scripts/manual-overrides.ts

@@ -37,13 +37,20 @@ export interface ManualModelOverride {
 	maxTokens?: number;
 	/** Reasoning effort values as declared by NaN docs. An empty array means the parameter is accepted but depth is model-managed (not adjustable by the user). */
 	reasoningEffortValues?: string[];
+	/**
+	 * Mapping from pi-ai's user-facing thinking levels to model-specific effort
+	 * strings. Only the "off" key is needed to suppress runaway reasoning.
+	 * When `reasoning: "off"` maps to undefined in pi-ai, thinkingLevelMap.off
+	 * supplies the effort value that NaN understands (e.g. "none" or "minimal").
+	 */
+	thinkingLevelMap?: Partial<Record<string, string | null>>;
 	/** Required provenance note; emitted verbatim onto the generated entry. */
 	note: string;
 }
 
 /**
- * Reasoning effort values sourced from the NaN docs (https://nan.builders/docs/models
- * #controlling-reasoning, checked 2026-09-29).
+ * Manual reasoning effort values sourced from the NaN docs
+ * (https://nan.builders/docs/models #controlling-reasoning, checked 2026-09-29).
  *
  * models.dev has NO `reasoning_effort_values` field — only `reasoning_options`
  * (which is [{type:"toggle"}] or []), so this mapping must be hand-maintained
@@ -53,8 +60,16 @@ export interface ManualModelOverride {
  *
  * Per-model contract from the docs:
  * - glm5.3, glm5.3-flash: fully controllable (low/medium/high/max)
+ *   + minimal also accepted (issue #16, measured 2026-09-27): minimal
+ *     yields 38 reasoning tokens vs 2,288 for high — the docs simply
+ *     omitted it because it was not originally advertised, but it IS
+ *     accepted and effective by the gateway.
  * - qwen3.6, gemma4: none/minimal skip reasoning, others cap depth
- * - deepseek-v4-flash: any value accepted but model decides per-request
+ * - deepseek-v4-flash: any value accepted but only "none" deterministically
+ *   disables reasoning (issue #16, measured 2026-09-27); every other value
+ *   (minimal/low/medium/high/omitted) leaves 13-14K reasoning tokens with
+ *   runaway reasoning and finish_reason:"length" with ZERO answer. Since only
+ *   "none" has a measurable effect, the catalog declares ["none"].
  * - qwen3.8-flash, mimo-v2.6-flash: accepted, depth not adjustable
  *
  * (mimo-v2.5, which used to share that last row, was removed by NaN — absent
@@ -65,7 +80,7 @@ export interface ManualModelOverride {
  */
 export const REASONING_EFFORT_VALUES: Record<string, string[]> = {
 	"glm5.3": ["low", "medium", "high", "max"],
-	"glm5.3-flash": ["low", "medium", "high", "max"],
+	"glm5.3-flash": ["minimal", "low", "medium", "high", "max"],
 	"qwen3.6": ["none", "minimal", "low", "medium", "high", "max"],
 	"gemma4": ["none", "minimal", "low", "medium", "high", "max"],
 };
@@ -105,11 +120,48 @@ export const MANUAL_ONLY_MODELS: Record<string, ManualModelOverride> = {
 	},
 };
 
+/**
+ * Manual overrides keyed by model id. Fields override the models.dev-derived
+ * entry one-for-one. Every override carries a provenance note.
+ *
+ * Issue #16 (measured 2026-09-27 against live gateway, repro included):
+ * - deepseek-v4-flash: reasoning_effort_values=["none"] (only "none" suppresses);
+ *   thinkingLevelMap={off:"none"} (supplies reasoning_effort when pi maps
+ *   reasoning:"off" → undefined).
+ * - glm5.3-flash: reasoningEffortValues includes "minimal" (not documented but
+ *   effective); thinkingLevelMap={off:"minimal"} (supplies reasoning_effort
+ *   when pi maps reasoning:"off" → undefined).
+ * - qwen3.6, gemma4: the NaN docs already document `none` as "skip the
+ *   reasoning phase entirely" and state that with no parameter the model
+ *   defaults to reasoning ON (16,384-token budget), so off must send
+ *   `none` explicitly — thinkingLevelMap={off:"none"} (NaN docs
+ *   #controlling-reasoning, checked 2026-10-01). No measurement needed: the
+ *   docs are explicit about both the default and the `none` behavior.
+ */
 export const MANUAL_OVERRIDES: Record<string, ManualModelOverride> = {
 	"deepseek-v4-flash": {
 		input: ["text", "image"],
-		// Any value accepted but model decides per-request (no effect).
-		reasoningEffortValues: [],
-		note: "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. reasoning_effort_values=[]: the model decides per-request how much to reason (https://nan.builders/docs/models, checked 2026-09-25).",
+		reasoningEffortValues: ["none"],
+		thinkingLevelMap: { off: "none" },
+		note:
+			"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. " +
+			"reasoning_effort_values=[\"none\"] (issue #16, measured 2026-09-27 against live gateway, repro included in the issue): only \"none\" deterministically disables reasoning (0 reasoning tokens, answer produced). Every other value leaves 13-14K reasoning tokens and causes runaway reasoning (finish_reason:\"length\" with ZERO answer text). The catalog declares only [\"none\"] because the remaining values are useless noise. " +
+			"thinkingLevelMap { off: \"none\" } (issue #16, measured 2026-09-27): when pi maps reasoning:\"off\" to reasoningEffort:undefined, the thinkingLevelMap.off=\"none\" supplies the effort so the gateway receives reasoning_effort:\"none\" and does NOT enter runaway reasoning mode.",
+	},
+	"glm5.3-flash": {
+		thinkingLevelMap: { off: "minimal" },
+		note:
+			"thinkingLevelMap { off: \"minimal\" } (issue #16, measured 2026-09-27 against live gateway, repro included in the issue): when pi maps reasoning:\"off\" to reasoningEffort:undefined, the thinkingLevelMap.off=\"minimal\" supplies the effort so the gateway receives reasoning_effort:\"minimal\" (38 reasoning tokens + answer). Note: \"none\" does NOT suppress reasoning on glm5.3-flash (13,382 tokens) — only \"minimal\" was measured to be effective. " +
+			"reasoning_effort_values includes \"minimal\" (not documented by NaN docs but accepted and effective by the gateway, issue #16).",
+	},
+	"qwen3.6": {
+		thinkingLevelMap: { off: "none" },
+		note:
+			"thinkingLevelMap { off: \"none\" } (issue #16): NaN docs state that with no reasoning_effort parameter every model uses its own default and that default is reasoning ON for qwen3.6 (16,384-token budget), while `none` and `minimal` skip the reasoning phase entirely (https://nan.builders/docs/models#controlling-reasoning, checked 2026-10-01). pi maps reasoning:\"off\" to reasoningEffort:undefined, so without this map `thinking: off` sent no parameter and the model reasoned anyway; the map sends reasoning_effort:\"none\" and actually disables reasoning.",
+	},
+	"gemma4": {
+		thinkingLevelMap: { off: "none" },
+		note:
+			"thinkingLevelMap { off: \"none\" } (issue #16): NaN docs state that with no reasoning_effort parameter gemma4 defaults to reasoning ON (16,384-token budget), while `none`/`minimal` skip reasoning entirely (https://nan.builders/docs/models#controlling-reasoning, checked 2026-10-01). pi maps reasoning:\"off\" to reasoningEffort:undefined, so without this map `thinking: off` sent no parameter and the model reasoned anyway; the map sends reasoning_effort:\"none\" and actually disables reasoning.",
 	},
 };

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-29T22:08:21.449Z
+// Source: https://models.dev/api.json (provider "nan"), fetched 2026-10-01T10:56:14.717Z
 // 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.
@@ -28,7 +28,12 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 		},
 		"contextWindow": 1000000,
 		"maxTokens": 384000,
-		"reasoningEffortValues": [],
+		"reasoningEffortValues": [
+			"none"
+		],
+		"thinkingLevelMap": {
+			"off": "none"
+		},
 		"compat": {
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
@@ -38,7 +43,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 		},
 		"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 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. reasoning_effort_values=[]: the model decides per-request how much to reason (https://nan.builders/docs/models, checked 2026-09-25)."
+			"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. reasoning_effort_values=[\"none\"] (issue #16, measured 2026-09-27 against live gateway, repro included in the issue): only \"none\" deterministically disables reasoning (0 reasoning tokens, answer produced). Every other value leaves 13-14K reasoning tokens and causes runaway reasoning (finish_reason:\"length\" with ZERO answer text). The catalog declares only [\"none\"] because the remaining values are useless noise. thinkingLevelMap { off: \"none\" } (issue #16, measured 2026-09-27): when pi maps reasoning:\"off\" to reasoningEffort:undefined, the thinkingLevelMap.off=\"none\" supplies the effort so the gateway receives reasoning_effort:\"none\" and does NOT enter runaway reasoning mode."
 		],
 		"extras": {
 			"id": "deepseek-v4-flash",
@@ -99,6 +104,9 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"high",
 			"max"
 		],
+		"thinkingLevelMap": {
+			"off": "none"
+		},
 		"compat": {
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
@@ -107,7 +115,8 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"maxTokensField": "max_tokens"
 		},
 		"notes": [
-			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, 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."
+			"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.",
+			"thinkingLevelMap { off: \"none\" } (issue #16): NaN docs state that with no reasoning_effort parameter gemma4 defaults to reasoning ON (16,384-token budget), while `none`/`minimal` skip reasoning entirely (https://nan.builders/docs/models#controlling-reasoning, checked 2026-10-01). pi maps reasoning:\"off\" to reasoningEffort:undefined, so without this map `thinking: off` sent no parameter and the model reasoned anyway; the map sends reasoning_effort:\"none\" and actually disables reasoning."
 		],
 		"extras": {
 			"id": "gemma4",
@@ -171,11 +180,15 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 		"contextWindow": 1000000,
 		"maxTokens": 131072,
 		"reasoningEffortValues": [
+			"minimal",
 			"low",
 			"medium",
 			"high",
 			"max"
 		],
+		"thinkingLevelMap": {
+			"off": "minimal"
+		},
 		"compat": {
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
@@ -184,7 +197,8 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"maxTokensField": "max_tokens"
 		},
 		"notes": [
-			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, 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."
+			"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.",
+			"thinkingLevelMap { off: \"minimal\" } (issue #16, measured 2026-09-27 against live gateway, repro included in the issue): when pi maps reasoning:\"off\" to reasoningEffort:undefined, the thinkingLevelMap.off=\"minimal\" supplies the effort so the gateway receives reasoning_effort:\"minimal\" (38 reasoning tokens + answer). Note: \"none\" does NOT suppress reasoning on glm5.3-flash (13,382 tokens) — only \"minimal\" was measured to be effective. reasoning_effort_values includes \"minimal\" (not documented by NaN docs but accepted and effective by the gateway, issue #16)."
 		],
 		"extras": {
 			"id": "glm5.3-flash",
@@ -316,6 +330,9 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"high",
 			"max"
 		],
+		"thinkingLevelMap": {
+			"off": "none"
+		},
 		"compat": {
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
@@ -324,7 +341,8 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"maxTokensField": "max_tokens"
 		},
 		"notes": [
-			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, 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."
+			"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.",
+			"thinkingLevelMap { off: \"none\" } (issue #16): NaN docs state that with no reasoning_effort parameter every model uses its own default and that default is reasoning ON for qwen3.6 (16,384-token budget), while `none` and `minimal` skip the reasoning phase entirely (https://nan.builders/docs/models#controlling-reasoning, checked 2026-10-01). pi maps reasoning:\"off\" to reasoningEffort:undefined, so without this map `thinking: off` sent no parameter and the model reasoned anyway; the map sends reasoning_effort:\"none\" and actually disables reasoning."
 		],
 		"extras": {
 			"id": "qwen3.6",
@@ -437,7 +455,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 export const GENERATED_CATALOG_META = {
 	source: "https://models.dev/api.json",
 	modelsDevProvider: "nan",
-	fetchedAt: "2026-09-29T22:08:21.449Z",
+	fetchedAt: "2026-10-01T10:56:14.717Z",
 	modelCount: 6,
 	models: ["deepseek-v4-flash","gemma4","glm5.3-flash","mimo-v2.6-flash","qwen3.6","qwen3.8-flash"],
 	notes: [
@@ -445,9 +463,17 @@ export const GENERATED_CATALOG_META = {
 	"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)",
 	"provider-removed: \"mimo-v2.5\" excluded from the catalog (removed by NaN (checked 2026-09-29): zero mentions in https://nan.builders/docs/models and in the model param description of https://nan.builders/openapi.json, and models.dev provider nan dropped it as well — superseded by mimo-v2.6-flash; excluded so regeneration does not resurrect it)",
+	"non-chat: \"qwen3-embedding\" excluded from the chat catalog (embedding endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model)",
+	"non-chat: \"rerank\" excluded from the chat catalog (rerank endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model)",
+	"non-chat: \"kokoro\" excluded from the chat catalog (text-to-speech (TTS) endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model)",
+	"non-chat: \"whisper\" excluded from the chat catalog (speech-to-text (STT) endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model)",
+	"non-chat: \"flux-2-klein\" excluded from the chat catalog (image generation endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model)",
 	"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. reasoning_effort_values=[]: the model decides per-request how much to reason (https://nan.builders/docs/models, checked 2026-09-25).",
+	"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. reasoning_effort_values=[\"none\"] (issue #16, measured 2026-09-27 against live gateway, repro included in the issue): only \"none\" deterministically disables reasoning (0 reasoning tokens, answer produced). Every other value leaves 13-14K reasoning tokens and causes runaway reasoning (finish_reason:\"length\" with ZERO answer text). The catalog declares only [\"none\"] because the remaining values are useless noise. thinkingLevelMap { off: \"none\" } (issue #16, measured 2026-09-27): when pi maps reasoning:\"off\" to reasoningEffort:undefined, the thinkingLevelMap.off=\"none\" supplies the effort so the gateway receives reasoning_effort:\"none\" and does NOT enter runaway reasoning mode.",
+	"thinkingLevelMap { off: \"none\" } (issue #16): NaN docs state that with no reasoning_effort parameter gemma4 defaults to reasoning ON (16,384-token budget), while `none`/`minimal` skip reasoning entirely (https://nan.builders/docs/models#controlling-reasoning, checked 2026-10-01). pi maps reasoning:\"off\" to reasoningEffort:undefined, so without this map `thinking: off` sent no parameter and the model reasoned anyway; the map sends reasoning_effort:\"none\" and actually disables reasoning.",
+	"thinkingLevelMap { off: \"minimal\" } (issue #16, measured 2026-09-27 against live gateway, repro included in the issue): when pi maps reasoning:\"off\" to reasoningEffort:undefined, the thinkingLevelMap.off=\"minimal\" supplies the effort so the gateway receives reasoning_effort:\"minimal\" (38 reasoning tokens + answer). Note: \"none\" does NOT suppress reasoning on glm5.3-flash (13,382 tokens) — only \"minimal\" was measured to be effective. reasoning_effort_values includes \"minimal\" (not documented by NaN docs but accepted and effective by the gateway, issue #16).",
 	"manual-only: \"mimo-v2.6-flash\" skipped: models.dev provider \"nan\" now lists it, so the manual-only entry is not emitted and the models.dev values are used (omnimodal model (text, image, audio input) served by NaN; limits and modalities from https://nan.builders/docs/models#mimo-v2-6-flash (checked 2026-09-25, quotas re-checked 2026-09-29): 1,048,576 context / 131,072 max output / 1.0B monthly quota per member. Reasoning: accepted, depth not adjustable (docs table, checked 2026-09-29). Tool calling: yes. Streaming: yes. Input modalities (pi-representable): text, image (audio not representable in pi's Model type). Fallback entry: emitted only while models.dev provider nan does not list the model — models.dev started listing it on 2026-09-29, so the generator then keeps the models.dev values and attaches this note to that entry instead of emitting a second one.)",
+	"thinkingLevelMap { off: \"none\" } (issue #16): NaN docs state that with no reasoning_effort parameter every model uses its own default and that default is reasoning ON for qwen3.6 (16,384-token budget), while `none` and `minimal` skip the reasoning phase entirely (https://nan.builders/docs/models#controlling-reasoning, checked 2026-10-01). pi maps reasoning:\"off\" to reasoningEffort:undefined, so without this map `thinking: off` sent no parameter and the model reasoned anyway; the map sends reasoning_effort:\"none\" and actually disables reasoning.",
 	"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)."
 ],
 } as const;

package/src/commands.ts

@@ -28,8 +28,9 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { mediaMcpCommand, mediaMcpEnabled, mediaMcpSource, mediaMcpEnvExplicit, mediaMcpEnvTruthy, mediaMcpTimeoutSec } from "./mcp/media-server.ts";
 import { webSearchBridgeEnabled, webSearchBridgeSource, mcpToolsEnvExplicit, mcpToolsDisabled } from "./mcp/api-key.ts";
-import { NAN_API_KEY_ENV, tryResolveNanApiKeyViaRegistry } from "./mcp/api-key.ts";
-import { NAN_STATE_FILE, readBridgeState, writeBridgeState, type BridgeKey, readState, writeState } from "./mcp/state.ts";
+import { NAN_API_KEY_ENV, tryResolveNanApiKeyViaRegistry, resolveStoredNanApiKey } from "./mcp/api-key.ts";
+import { NAN_STATE_FILE, MCP_SERVER_NAMES, readBridgeState, writeBridgeState, type BridgeKey, readState, writeState } from "./mcp/state.ts";
+import { connectorMissingMessage, hasMcpConnector } from "./mcp/host-support.ts";
 
 const USAGE =
 	"Usage: /nan-mcp [status] · /nan-mcp enable [web-search|nan-mcp-server] · /nan-mcp disable [web-search|nan-mcp-server]";
@@ -67,7 +68,7 @@ function sourceLabel(bridge: BridgeKey, source: "env" | "persisted" | "default")
 
 /** Resolve a bridge key to its native server name. */
 function serverName(bridge: BridgeKey): string {
-	return bridge === "webSearch" ? "nan-search" : "nan-media";
+	return MCP_SERVER_NAMES[bridge];
 }
 
 /** Describe the bridge in the status message. */
@@ -86,10 +87,16 @@ function nativeServerRegistered(pi: ExtensionAPI, name: string): boolean {
 	}
 }
 
-/** Status message listing both bridges' gate state and native registration. */
-function statusMessage(pi: ExtensionAPI): string {
+/** Status message listing both bridges' gate state and native registration.
+ * `ctx` is the command context (provides modelRegistry for key lookup).
+ */
+async function statusMessage(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<string> {
 	const lines: string[] = [];
 
+	if (!hasMcpConnector(pi)) {
+		lines.push(connectorMissingMessage([MCP_SERVER_NAMES.webSearch, MCP_SERVER_NAMES.mediaMcp]));
+	}
+
 	for (const bridge of ["webSearch" as BridgeKey, "mediaMcp" as BridgeKey]) {
 		const enabled = bridge === "webSearch" ? webSearchBridgeEnabled() : mediaMcpEnabled();
 		const source = bridge === "webSearch" ? webSearchBridgeSource() : mediaMcpSource();
@@ -98,7 +105,7 @@ function statusMessage(pi: ExtensionAPI): string {
 
 		if (bridge === "webSearch") {
 			// Key status for web-search
-			const keyStatus = resolveKeyStatus(pi);
+			const keyStatus = await resolveKeyStatus(ctx);
 			lines.push(`  API key: ${keyStatus}.`);
 		}
 		if (bridge === "mediaMcp") {
@@ -110,12 +117,14 @@ function statusMessage(pi: ExtensionAPI): string {
 	return lines.join("\n");
 }
 
-/** Check API key resolution status for web-search. */
-async function resolveKeyStatus(pi: ExtensionAPI): Promise<string> {
-	// @ts-expect-error — modelRegistry is a runtime surface.
-	const registryKey = await tryResolveNanApiKeyViaRegistry(pi.modelRegistry);
+/** Check API key resolution status for web-search.
+ * `ctx` is the command context (provides modelRegistry).
+ */
+async function resolveKeyStatus(ctx: ExtensionCommandContext): Promise<string> {
+	const registryKey = await tryResolveNanApiKeyViaRegistry(ctx.modelRegistry);
+	const storedKey = resolveStoredNanApiKey();
 	const envKey = process.env[NAN_API_KEY_ENV];
-	if (registryKey || envKey) return "resolved";
+	if (registryKey || storedKey || envKey) return "resolved";
 	return "NOT SET — run /login nan or export NAN_API_KEY";
 }
 
@@ -161,7 +170,7 @@ export function registerNanMcpCommand(pi: ExtensionAPI): void {
 			const subcommand = rawSubcommand.toLowerCase();
 
 			if (subcommand === "status") {
-				ctx.ui.notify(statusMessage(pi), "info");
+				ctx.ui.notify(await statusMessage(pi, ctx), "info");
 				return;
 			}
 
@@ -183,6 +192,22 @@ export function registerNanMcpCommand(pi: ExtensionAPI): void {
 					writeBridgeState(bridge, enabled);
 				}
 
+				const where = target ? `for "${target}"` : "for both bridges";
+				const persistence = `persisted in <agentDir>/${NAN_STATE_FILE}`;
+
+				// Without an extension that handles `mcp_servers_change` pi cannot connect the
+				// servers; registering would only trigger its "no loaded extension connects MCP
+				// servers" error (see src/mcp/host-support.ts). The toggle above still persists,
+				// so it applies as soon as a connector (built-in `mcp`) is available.
+				if (enabled && !hasMcpConnector(pi)) {
+					ctx.ui.notify(
+						`Enabled ${describeBridges(bridges)} ${where}, ${persistence} — NOT registered. ` +
+							connectorMissingMessage(bridges.map(serverName)),
+						"warning",
+					);
+					return;
+				}
+
 				// Immediate native registration/unregistration.
 				for (const bridge of bridges) {
 					const name = serverName(bridge);
@@ -190,9 +215,10 @@ export function registerNanMcpCommand(pi: ExtensionAPI): void {
 						// Only register if gate allows it.
 						if (bridgeEffectivelyEnabled(bridge)) {
 							if (bridge === "webSearch") {
-								// @ts-expect-error — modelRegistry is a runtime surface.
-								const registryKey = await tryResolveNanApiKeyViaRegistry(pi.modelRegistry);
-								const apiKey = registryKey ?? process.env[NAN_API_KEY_ENV];
+								// Resolve key: stored credential → registry → env.
+								const registryKey = await tryResolveNanApiKeyViaRegistry(ctx.modelRegistry);
+								const storedKey = resolveStoredNanApiKey();
+								const apiKey = storedKey ?? registryKey ?? process.env[NAN_API_KEY_ENV];
 								if (apiKey) {
 									pi.registerMcpServer(name, {
 										type: "http",
@@ -207,15 +233,26 @@ export function registerNanMcpCommand(pi: ExtensionAPI): void {
 									);
 								}
 							} else {
-								const mediaArgs = mediaMcpCommand();
-								pi.registerMcpServer(name, {
-									type: "stdio",
-									command: mediaArgs[0]!,
-									args: mediaArgs.slice(1),
-									env: { [NAN_API_KEY_ENV]: process.env[NAN_API_KEY_ENV] ?? "" },
-									exposure: "direct",
-									timeout: mediaMcpTimeoutSec(),
-								});
+								// Resolve key for media: stored credential → registry → env.
+								const registryKey = await tryResolveNanApiKeyViaRegistry(ctx.modelRegistry);
+								const storedKey = resolveStoredNanApiKey();
+								const apiKey = storedKey ?? registryKey ?? process.env[NAN_API_KEY_ENV];
+								if (apiKey) {
+									const mediaArgs = mediaMcpCommand();
+									pi.registerMcpServer(name, {
+										type: "stdio",
+										command: mediaArgs[0]!,
+										args: mediaArgs.slice(1),
+										env: { [NAN_API_KEY_ENV]: apiKey },
+										exposure: "direct",
+										timeout: mediaMcpTimeoutSec(),
+									});
+								} else {
+									ctx.ui.notify(
+										`${NAN_API_KEY_ENV} is not set. Export it or run /login nan.`,
+										"warning",
+									);
+								}
 							}
 						}
 					} else {
@@ -223,13 +260,22 @@ export function registerNanMcpCommand(pi: ExtensionAPI): void {
 					}
 				}
 
-				const where = target ? `for "${target}"` : "for both bridges";
-				const persistence = `persisted in <agentDir>/${NAN_STATE_FILE}`;
 				if (enabled) {
-					ctx.ui.notify(
-						`Enabled ${describeBridges(bridges)} ${where}, ${persistence}. Native servers registered for this session.`,
-						"info",
+					// Only claim success if servers were actually registered.
+					const allRegistered = bridges.every((b: BridgeKey) =>
+						nativeServerRegistered(pi, serverName(b)),
 					);
+					if (allRegistered) {
+						ctx.ui.notify(
+							`Enabled ${describeBridges(bridges)} ${where}, ${persistence}. Native servers registered for this session.`,
+							"info",
+						);
+					} else {
+						ctx.ui.notify(
+							`Enabled ${describeBridges(bridges)} ${where}, ${persistence} — API key missing; servers not registered.`,
+							"warning",
+						);
+					}
 				} else {
 					ctx.ui.notify(
 						`Disabled ${describeBridges(bridges)} ${where}, ${persistence}. Native servers unregistered — tools hidden immediately.`,

package/src/cross-model-thinking-guard.ts

@@ -65,6 +65,14 @@ export function crossModelThinkingGuardEnabled(env: NodeJS.ProcessEnv = process.
 	return value !== "0" && value !== "false" && value !== "no" && value !== "off";
 }
 
+/**
+ * API id pi 0.99 assigns to virtual catalog entries (`core/virtual-models.js`,
+ * `VIRTUAL_MODEL_API`). A virtual selection routes each request to a physical
+ * model; the physical target is not exposed to the `context` hook, so the guard
+ * cannot tell which physical model will answer.
+ */
+const VIRTUAL_MODEL_API = "pi-virtual";
+
 function isGuardMessage(value: unknown): value is GuardMessage {
 	return typeof value === "object" && value !== null;
 }
@@ -85,6 +93,16 @@ export function stripCrossModelThinking<T>(
 ): readonly T[] {
 	if (!target?.provider || !options.providerIds.has(target.provider)) return messages;
 
+	// Virtual selection (pi 0.99): `ctx.model` is the selectable virtual entry
+	// (api "pi-virtual"), not the physical model the router picks for this
+	// request. Its api/id never match a physical assistant message, so the
+	// same-model check below would strip reasoning on EVERY continuation —
+	// including when the router keeps the same physical model — losing the
+	// prompt cache and thinking continuity the guard promises to preserve.
+	// The routed physical model is not available here, so skip virtual
+	// selections entirely; cross-model trimming is the router's concern there.
+	if (target.api === VIRTUAL_MODEL_API) return messages;
+
 	let changed = false;
 
 	const next = messages.map((raw) => {

package/src/fetch-models.ts

@@ -12,16 +12,19 @@
  *     only model `id`s — no capability fields. It is used as the authoritative
  *     list of what the endpoint returns for the API key.
  *
- * Merge: live IDs × generated capability data — all live IDs surface:
- * a live ID with generated data keeps its generated capabilities, and an
- * uncatalogued live ID (e.g. a new or undocumented model) gets conservative
- * placeholder limits (the same defaults used in custom-provider.md's
- * dynamic-discovery example) with no reasoning support — capabilities stay
- * "unknown", nothing is fabricated. On fetch failure, timeout, or an unusable
- * response, callers fall back to the generated catalog so startup is never blocked.
+ * Merge: live IDs × generated capability data — non-chat IDs (see
+ * `NON_CHAT_MODEL_IDS`) are excluded from the registered model set and
+ * reported in `MergedCatalog.nonChat`; all other live IDs surface: a live ID
+ * with generated data keeps its generated capabilities, and an uncatalogued
+ * live ID (e.g. a new or undocumented model) gets conservative placeholder
+ * limits (the same defaults used in custom-provider.md's dynamic-discovery
+ * example) with no reasoning support — capabilities stay "unknown", nothing is
+ * fabricated. On fetch failure, timeout, or an unusable response, callers fall
+ * back to the generated catalog so startup is never blocked.
  */
 
 import type { Model, OpenAICompletionsCompat } from "@earendil-works/pi-ai";
+import type { ThinkingLevelMap } from "@earendil-works/pi-ai";
 import { GENERATED_CATALOG_META, NAN_GENERATED_MODELS } from "../scripts/models.generated.ts";
 
 export type { Model };
@@ -46,6 +49,15 @@ export interface GeneratedModelEntry {
 	 * An undefined array means the field was not set (legacy / uncatalogued).
 	 */
 	reasoningEffortValues?: string[];
+	/**
+	 * Mapping from pi-ai's user-facing thinking levels to model-specific effort
+	 * strings. When `reasoning: "off"` maps to undefined in pi-ai,
+	 * thinkingLevelMap.off supplies the effort value that NaN understands
+	 * (e.g. "none" for deepseek-v4-flash, "minimal" for glm5.3-flash).
+	 * Without this, no reasoning_effort is sent and NaN does NOT disable
+	 * reasoning, causing runaway reasoning (issue #16).
+	 */
+	thinkingLevelMap?: ThinkingLevelMap;
 	/** Compat applied to every NaN-compatible model (LiteLLM-confirmed, see scripts/generate-models.ts). */
 	compat?: OpenAICompletionsCompat;
 	/** Provenance notes for values overriding models.dev or needing manual confirmation. */
@@ -71,6 +83,32 @@ export const UNKNOWN_MODEL_LIMITS = { contextWindow: 128_000, maxTokens: 4_096 }
 /** Timeout for the live /models fetch; matches the pi-synthetic-provider precedent (~3s). */
 export const DEFAULT_MODELS_TIMEOUT_MS = 3_000;
 
+/**
+ * Live endpoint IDs classified as non-chat and excluded from the registered
+ * model set. Keys are model ids; values are provenance reasons citing the
+ * source that designated the endpoint as non-chat.
+ *
+ * Source: https://nan.builders/docs/models (checked 2026-10-01), plus
+ * qwen-image-2.1: https://models.dev API `limit.output: 0` (checked 2026-09-29).
+ * These are MCP-bridge territory (embedding / rerank / TTS / STT / image
+ * generation), not chat catalog models — see AGENTS.md classification notes
+ * and issue #15.
+ */
+export const NON_CHAT_MODEL_IDS: Readonly<Record<string, string>> = {
+	"qwen3-embedding":
+		"embedding endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model",
+	rerank:
+		"rerank endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model",
+	kokoro:
+		"text-to-speech (TTS) endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model",
+	whisper:
+		"speech-to-text (STT) endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model",
+	"flux-2-klein":
+		"image generation endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model",
+	"qwen-image-2.1":
+		"image-generation model (text→image; output modality image) documented in https://nan.builders/docs/models and https://nan.builders/openapi.json (checked 2026-09-29) — not a chat model, out of the static chat catalog (models.dev reports limit.output 0)",
+} as const;
+
 export interface CatalogSource {
 	/** Provider id as registered in pi, e.g. "nan". */
 	providerId: string;
@@ -92,12 +130,17 @@ export function toModel(entry: GeneratedModelEntry, source: CatalogSource): Mode
 		contextWindow: entry.contextWindow,
 		maxTokens: entry.maxTokens,
 		...(entry.compat ? { compat: { ...entry.compat } } : {}),
+		...(entry.thinkingLevelMap ? { thinkingLevelMap: { ...entry.thinkingLevelMap } } : {}),
 	};
 }
 
 /** The generated fallback catalog as pi-ai Models for the given provider. */
 export function baselineModels(source: CatalogSource): Model<"openai-completions">[] {
-	return NAN_GENERATED_MODELS.map((entry) => toModel(entry, source));
+	// Defensive: the generated baseline never contains non-chat ids today,
+	// but the invariant must hold on every path (issue #15).
+	return NAN_GENERATED_MODELS.filter(
+		(entry) => !NON_CHAT_MODEL_IDS[entry.id],
+	).map((entry) => toModel(entry, source));
 }
 
 export interface LiveModelListOptions {
@@ -152,12 +195,18 @@ export interface MergedCatalog {
 	matched: string[];
 	/** Allowlisted live IDs kept with unknown capabilities (conservative limits). */
 	unknown: string[];
+	/**
+	 * Live model IDs classified as non-chat and excluded from the registered
+	 * model set, in live order. Populated from `NON_CHAT_MODEL_IDS` (issue #15).
+	 */
+	nonChat: string[];
 }
 
 /**
- * Merge live model IDs with the generated capability catalog. All live IDs
- * surface: live IDs with generated data keep their generated capabilities;
- * uncatalogued live IDs get conservative placeholder limits,
+ * Merge live model IDs with the generated capability catalog. Non-chat IDs
+ * (from `NON_CHAT_MODEL_IDS`) are excluded and reported in `nonChat`; all
+ * other live IDs surface: live IDs with generated data keep their generated
+ * capabilities; uncatalogued live IDs get conservative placeholder limits,
  * `reasoning: false`, and zero cost (documented defaults, not invented
  * capabilities).
  */
@@ -170,8 +219,15 @@ export function mergeLiveWithGenerated(
 	const models: Model<"openai-completions">[] = [];
 	const matched: string[] = [];
 	const unknown: string[] = [];
+	const nonChat: string[] = [];
 
 	for (const id of liveIds) {
+		// Issue #15: non-chat endpoint ids must never surface as chat models.
+		const nonChatReason = NON_CHAT_MODEL_IDS[id];
+		if (nonChatReason) {
+			nonChat.push(id);
+			continue;
+		}
 		const entry = byId.get(id);
 		if (entry) {
 			models.push(toModel(entry, source));
@@ -206,7 +262,7 @@ export function mergeLiveWithGenerated(
 		}
 	}
 
-	return { models, matched, unknown };
+	return { models, matched, unknown, nonChat };
 }
 
 export interface FetchModelsOptions {
@@ -229,13 +285,19 @@ export interface ResolvedCatalog {
 	liveIds: Set<string> | undefined;
 	/** Allowlisted live IDs kept with unknown capabilities (present only when liveIds is set). */
 	unknownIds: string[];
+	/**
+	 * Live model IDs classified as non-chat and excluded from the registered
+	 * model set (issue #15). Empty when the live fetch failed.
+	 */
+	nonChatIds: string[];
 }
 
 /**
  * Resolve the effective catalog: live `/models` IDs × generated capability
  * data. A successful live fetch is authoritative (tier-aware: it reflects
  * exactly what your NaN key can use); failure degrades to the generated
- * fallback so startup is never blocked.
+ * fallback so startup is never blocked. Non-chat IDs are excluded from
+ * models and reported in `nonChatIds` (issue #15).
  */
 export async function resolveCatalog(
 	source: CatalogSource,
@@ -249,11 +311,16 @@ export async function resolveCatalog(
 			timeoutMs: options.timeoutMs,
 			fetchImpl: options.fetchImpl,
 		});
-		if (!liveIds) return { models: baseline, liveIds: undefined, unknownIds: [] };
+		if (!liveIds) return { models: baseline, liveIds: undefined, unknownIds: [], nonChatIds: [] };
 		const merged = mergeLiveWithGenerated(liveIds, source);
-		return { models: merged.models, liveIds: new Set(liveIds), unknownIds: merged.unknown };
+		return {
+			models: merged.models,
+			liveIds: new Set(liveIds),
+			unknownIds: merged.unknown,
+			nonChatIds: merged.nonChat,
+		};
 	} catch {
-		return { models: baseline, liveIds: undefined, unknownIds: [] };
+		return { models: baseline, liveIds: undefined, unknownIds: [], nonChatIds: [] };
 	}
 }
 

package/src/index.ts

@@ -39,8 +39,9 @@ import {
 import { baselineModels } from "./fetch-models.ts";
 import { createNanCompatibleProvider, type OpenAICompatibleProviderConfig } from "./provider-factory.ts";
 import { PROVIDERS } from "./providers.ts";
-import { NAN_API_KEY_ENV, mcpToolsDisabled, mcpToolsEnvExplicit, resolveNanApiKey, tryResolveNanApiKeyViaRegistry, NAN_MCP_TOOLS_ENV, webSearchBridgeEnabled } from "./mcp/api-key.ts";
+import { NAN_API_KEY_ENV, mcpToolsDisabled, mcpToolsEnvExplicit, resolveNanApiKey, tryResolveNanApiKeyViaRegistry, resolveStoredNanApiKey, NAN_MCP_TOOLS_ENV, webSearchBridgeEnabled } from "./mcp/api-key.ts";
 import { mediaMcpCommand, mediaMcpEnabled, mediaMcpEnvExplicit, mediaMcpEnvTruthy, mediaMcpTimeoutSec } from "./mcp/media-server.ts";
+import { registerMcpHostGuard } from "./mcp/host-support.ts";
 
 /**
  * Register a provider on any pi version: the native full-Provider overload
@@ -78,6 +79,7 @@ async function registerProviderCompat(
 			contextWindow: model.contextWindow,
 			maxTokens: model.maxTokens,
 			...(model.compat ? { compat: { ...model.compat } } : {}),
+			...(model.thinkingLevelMap ? { thinkingLevelMap: { ...model.thinkingLevelMap } } : {}),
 		})),
 	};
 	pi.registerProvider(config.id, legacy);
@@ -93,10 +95,13 @@ const NO_NATIVE_MCP_GUARD_MSG =
 	"pi-nan-provider 0.10+ requires pi >= 0.99 for MCP tools (native MCP); upgrade pi or stay on package 0.9.x";
 
 /** Register the official NaN web-search MCP server (session-scoped). */
-async function registerWebSearchMcpServer(pi: ExtensionAPI): Promise<boolean> {
+async function registerWebSearchMcpServer(pi: ExtensionAPI, apiKey: string | undefined): Promise<boolean> {
 	if (!webSearchBridgeEnabled()) return false;
-	const apiKey = process.env[NAN_API_KEY_ENV];
 	if (!apiKey) {
+		console.warn(
+			"[pi-nan-provider] NAN_API_KEY is not set — web-search server not registered. " +
+				"Run `/login nan` in pi or export `NAN_API_KEY=<your-key>`.",
+		);
 		return false;
 	}
 	pi.registerMcpServer("nan-search", {
@@ -109,14 +114,21 @@ async function registerWebSearchMcpServer(pi: ExtensionAPI): Promise<boolean> {
 }
 
 /** Register the community media stdio MCP server (session-scoped). */
-function registerMediaMcpServer(pi: ExtensionAPI): boolean {
+function registerMediaMcpServer(pi: ExtensionAPI, apiKey: string | undefined): boolean {
 	if (!mediaMcpEnabled()) return false;
+	if (!apiKey) {
+		console.warn(
+			"[pi-nan-provider] NAN_API_KEY is not set — media server not registered. " +
+				"Run `/login nan` in pi or export `NAN_API_KEY=<your-key>`.",
+		);
+		return false;
+	}
 	const mediaArgs = mediaMcpCommand();
 	pi.registerMcpServer("nan-media", {
 		type: "stdio",
 		command: mediaArgs[0]!,
 		args: mediaArgs.slice(1),
-		env: { [NAN_API_KEY_ENV]: process.env[NAN_API_KEY_ENV] ?? "" },
+		env: { [NAN_API_KEY_ENV]: apiKey },
 		exposure: "direct",
 		timeout: mediaMcpTimeoutSec(),
 	});
@@ -141,11 +153,14 @@ async function registerMcpServersNative(pi: ExtensionAPI): Promise<void> {
 		return;
 	}
 
+	// Resolve the API key ONCE: stored credential (auth.json) → env fallback.
+	// The factory-time ExtensionAPI has NO modelRegistry; stored credentials
+	// must be read through the coding-agent's readStoredCredential API.
+	const storedKey = resolveStoredNanApiKey();
+	const apiKey = storedKey ?? process.env[NAN_API_KEY_ENV];
 
-	const didWebSearch = await registerWebSearchMcpServer(pi);
-	registerMediaMcpServer(pi);
-
-
+	await registerWebSearchMcpServer(pi, apiKey);
+	registerMediaMcpServer(pi, apiKey);
 }
 
 // ── Extension entrypoint ─────────────────────────────────────────────────
@@ -179,6 +194,9 @@ export function registerCrossModelThinkingGuard(pi: ExtensionAPI): void {
 
 export default async function nanProviderExtension(pi: ExtensionAPI): Promise<void> {
 	registerCrossModelThinkingGuard(pi);
+	// Replaces pi's cryptic "no loaded extension connects MCP servers" error with
+	// actionable guidance when the host loads no built-in `mcp` extension (PI WEB).
+	registerMcpHostGuard(pi);
 	for (const config of PROVIDERS) {
 		await registerProviderCompat(pi, config);
 	}

package/src/mcp/api-key.ts

@@ -1,4 +1,5 @@
 import { bridgeSource, resolveBridgeEnabled } from "./state.ts";
+import { readStoredCredential } from "@earendil-works/pi-coding-agent";
 
 /**
  * NaN API key resolution — shared across every surface (web search, media, usage).
@@ -7,6 +8,38 @@ import { bridgeSource, resolveBridgeEnabled } from "./state.ts";
  * Never logs or embeds the key beyond the Authorization header.
  */
 
+/**
+ * Resolve the NaN API key through pi's stored credential (auth.json).
+ * Reads synchronously via `readStoredCredential("nan")` — the factory-time
+ * ExtensionAPI has NO modelRegistry (verified pi 0.99.1); stored credentials
+ * must be resolved at load time through the coding-agent API.
+ *
+ * Guards the credential shape: only accepts `{ type: "api_key", key: "sk-..." }`
+ * with a non-empty string key. Wraps in try/catch → undefined on any error.
+ *
+ * Precedence: this function is the **stored-credential** layer; callers compose
+ * it with the env var fallback to achieve stored → env order.
+ */
+export function resolveStoredNanApiKey(): string | undefined {
+	try {
+		const credential = readStoredCredential(NAN_PROVIDER_ID);
+		if (
+			credential != null &&
+			typeof credential === "object" &&
+			"type" in credential &&
+			credential.type === "api_key" &&
+			"key" in credential &&
+			typeof credential.key === "string" &&
+			credential.key.length > 0
+		) {
+			return credential.key;
+		}
+		return undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 /** Env var that overrides the official web_search bridge. */
 export const NAN_MCP_TOOLS_ENV = "NAN_MCP_TOOLS";
 /** Env var that overrides the media bridge. */

package/src/mcp/host-support.ts

@@ -0,0 +1,94 @@
+/**
+ * Host-side MCP connector detection plus the `session_start` guard that keeps
+ * this package's registrations from tripping pi's cryptic extension error.
+ *
+ * pi connects servers registered with `pi.registerMcpServer()` from the
+ * built-in `mcp` extension: it registers the `/mcp` command and handles
+ * `mcp_servers_change`. When NO loaded extension handles that event, pi reports
+ * every registration as an extension error right after the `session_start`
+ * emit (`ExtensionRunner.reportUnhandledMcpServers()` called from
+ * `AgentSession.bindExtensions()`):
+ *
+ *   MCP server "nan-media" is registered, but no loaded extension connects MCP
+ *   servers; another extension may have replaced the built-in MCP support
+ *
+ * Hosts that build pi's `DefaultResourceLoader` without `extensionFactories`
+ * load no `builtin:*` extension at all — including `builtin:mcp`. PI WEB does
+ * exactly that (`createAgentSessionServices` → `new DefaultResourceLoader(...)`,
+ * verified on pi 0.99.1 / pi-web 1.202609.1), so in every PI WEB session this
+ * package's registrations are dead and pi reports the error above.
+ *
+ * Detection: the built-in MCP extension always registers `/mcp`, and pi's
+ * replacement contract is phrased in the same terms ("an extension that
+ * registers `/mcp` ... replaces the built-in one"). When `pi.getCommands()` is
+ * unavailable (older pi, minimal mocks) the answer is unknowable, so we stay
+ * conservative and assume a connector exists — pi's own behavior is untouched.
+ *
+ * With no connector we claim `mcp_servers_change` ourselves: handling the event
+ * is pi's signal that somebody connects the servers, so its report stays silent
+ * and our warning (with the fix) replaces the cryptic one. The claim is
+ * released by a later `session_start` that finds a connector. Known trade-off:
+ * while claimed, pi's report is silent for every extension's registration, not
+ * only ours — that is the price of replacing an error we cannot scope, and our
+ * warning still names the missing connector.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { MCP_SERVER_NAMES } from "./state.ts";
+
+/** Built-in MCP command; duplicate registrations resolve to `mcp:<n>`. */
+const MCP_COMMAND_PATTERN = /^mcp(?::\d+)?$/;
+
+/** Servers this package registers; only they are ours to explain or claim for. */
+const OWNED_SERVER_NAMES: string[] = Object.values(MCP_SERVER_NAMES);
+
+/**
+ * Whether some loaded extension connects MCP servers.
+ *
+ * `true` whenever it cannot be determined (no `pi.getCommands()`), so callers
+ * only ever act on a positively missing connector.
+ */
+export function hasMcpConnector(pi: ExtensionAPI): boolean {
+	if (typeof pi.getCommands !== "function") return true;
+	try {
+		const commands = pi.getCommands();
+		if (!Array.isArray(commands)) return true;
+		return commands.some((command) => MCP_COMMAND_PATTERN.test(command?.name ?? ""));
+	} catch {
+		return true;
+	}
+}
+
+/** Actionable explanation of a missing connector, naming the affected servers. */
+export function connectorMissingMessage(serverNames: string[]): string {
+	const names = serverNames.map((name) => `\`${name}\``).join(" and ");
+	return (
+		"MCP connector: MISSING — no loaded extension connects MCP servers in this session " +
+		"(pi's built-in `/mcp` command is not loaded), so " +
+		`${names} cannot expose tools. Load the built-in connector with \`pi config\` ` +
+		"→ Built-in extensions → `mcp`; hosts that load no built-in extensions " +
+		"(PI WEB sessions) have no MCP support at all."
+	);
+}
+
+/**
+ * Guard against pi's "registered, but no loaded extension connects MCP servers"
+ * error. Registered from the extension entrypoint; see the module comment.
+ */
+export function registerMcpHostGuard(pi: ExtensionAPI): void {
+	if (typeof pi.on !== "function") return; // old pi without event hooks
+	let releaseClaim: (() => void) | undefined;
+	pi.on("session_start", (_event, ctx) => {
+		releaseClaim?.();
+		releaseClaim = undefined;
+		const registered = typeof pi.getMcpServers === "function" ? pi.getMcpServers() : [];
+		const owned = registered
+			.map((server) => server.name)
+			.filter((name) => OWNED_SERVER_NAMES.includes(name));
+		// Nothing registered (pi <0.99 guard, gates off) → nothing to explain.
+		if (owned.length === 0) return;
+		if (hasMcpConnector(pi)) return;
+		releaseClaim = pi.on("mcp_servers_change", () => {});
+		ctx.ui.notify(connectorMissingMessage(owned), "warning");
+	});
+}

package/src/mcp/state.ts

@@ -25,6 +25,12 @@ export interface NanProviderState {
 
 export type BridgeKey = keyof NanProviderState;
 
+/** Server name each bridge registers with `pi.registerMcpServer()`. Single source of truth. */
+export const MCP_SERVER_NAMES: Record<BridgeKey, string> = {
+	webSearch: "nan-search",
+	mediaMcp: "nan-media",
+};
+
 export type BridgeSource = "env" | "persisted" | "default";
 
 function stateFilePath(): string {