@gtrabanco/pi-nan-provider 1.0.1 → 1.2.1

package/AGENTS.md

@@ -172,20 +172,43 @@ Since 1.0.0 the package version **aligns its MAJOR.MINOR with the pi release lin
   override (maintainer-confirmed 2026-09-05) was withdrawn 2026-09-07 — the
   updated NaN docs still say 262K "the model's native window" and models.dev
   agrees at 262,144.
+- **Catalog authority order** (maintainer instruction, 2026-10-14):
+  1. a **manual override**, as long as the docs have not changed since it was
+     written; 2. **https://nan.builders/docs/models** — the source of truth;
+  3. **models.dev** (provider `nan`). When the docs change and an override
+     predates the change, the docs win, **but the override must be re-verified
+     against the live gateway first** — a measured override usually encodes a
+     real failure mode the docs may not describe. **When the live probe
+     disagrees with the docs, the measurement wins** (maintainer instruction,
+     2026-10-14): the docs' `deepseek-v4-flash` "any value (no effect)" claim
+     was disproven by a re-probe, so the measured `none` behavior stayed.
+     models.dev is a
+     downstream mirror a human updates later than the docs or a Discord
+     announcement, so a divergence is never by itself proof the docs are
+     wrong. Every divergence or exclusion is recorded with provenance.
 - **Which models exist**: https://nan.builders/docs/models is the source of
   truth (maintainer instruction, reaffirmed 2026-09-29), cross-checked against
-  the `model` param description in https://nan.builders/openapi.json; models.dev
-  (provider `nan`) supplies the numeric limits for the ids it documents, and
-  every divergence or exclusion is recorded with provenance.
-  Official chat models (checked 2026-09-29): community `deepseek-v4-flash`,
+  the `model` param description in https://nan.builders/openapi.json. All seven
+  chat models declare 1M-token windows where the docs say so —
+  `deepseek-v4-flash`, `glm5.3-flash`, `qwen3.8-flash` and `mimo-v2.6-flash` at
+  **1,048,576**, `qwen3.6` and `gemma4` at **262,144** — and the first three
+  carry a `MANUAL_OVERRIDES.contextWindow` because models.dev lagged (rounded
+  1,000,000 for the first two, stale 262,144 for `qwen3.8-flash`; docs checked
+  2026-10-14).
+  Official chat models (checked 2026-10-14): community `deepseek-v4-flash`,
   `mimo-v2.6-flash`, `qwen3.8-flash`, `glm5.3-flash`, `qwen3.6`, `gemma4`
   (all text+image vision) + premium-tier `glm5.3`
-  (~753B MoE, text-only input, 1M context, 400M tokens/rolling 4h window).
-  glm5.3 is now documented by models.dev too (1M context / 131,072 max output,
-  checked 2026-09-13) but stays out of the static catalog via
-  `LIVE_ONLY_MODEL_IDS` (premium tier) so a non-premium key never sees a
-  model it cannot call when the live `/models` fetch is unavailable; premium
-  keys still receive it live with conservative placeholder limits.
+  (~753B MoE, multimodal text+image+audio+video input, 1M context, 400M
+  tokens/rolling 4h window).
+  glm5.3 stays out of the static catalog via `LIVE_ONLY_MODEL_IDS` (premium
+  tier) so a non-premium key never sees a model it cannot call when the live
+  `/models` fetch is unavailable. Premium keys receive it live with its
+  DOCUMENTED capabilities, not a blind placeholder: `LIVE_ONLY_MODEL_DATA` in
+  `src/fetch-models.ts` (1,048,576 / 131,072, text+image, `thinkingLevelMap
+  { off: "low" }`) is applied both by `mergeLiveWithGenerated` and by
+  `buildOverlayMap`, so a stored `glm5.3` entry is also corrected. The store
+  still decides which ids exist; the table only decides their capabilities
+  (issue #19's invariant is intact).
   Removed by the provider: `glm5.2` (2026-09-05) and `mimo-v2.5` (checked
   2026-09-29 — zero mentions in the docs and in openapi.json, and models.dev
   dropped it too; superseded by `mimo-v2.6-flash`). models.dev may re-list a
@@ -247,34 +270,38 @@ Since 1.0.0 the package version **aligns its MAJOR.MINOR with the pi release lin
   the `SessionEntry` union, expanded `TurnEndEvent`, removed `shouldStopAfterTurn`,
   `SessionManager` canonical for provider context. The package touches none of them.
 - Since 0.10.0, this package uses native MCP via `pi.registerMcpServer()`.
-  Both servers are session-scoped, visible in `/mcp` with source "extension".
+  The server is session-scoped, visible in `/mcp` with source "extension".
   Server names and tool IDs:
-  - `nan-search` → tools: `mcp__nan_search__web_search`
-    (official remote, HTTP, `Authorization: Bearer <key>` header)
-  - `nan-media` → tools: `mcp__nan_media__generate_image/edit_image/text_to_speech/list_voices/speech_to_text/list_models/embed_text/rerank_documents`
-    (community stdio, `npx -y nan-mcp-server@1.1.2`, 120s timeout; 8 tools as of 1.1.2)
-  - `exposure: "direct"` on both — tools are declared to the model.
+  - `nan-media` → tools: `mcp__nan_media__generate_image/edit_image/text_to_speech/list_voices/speech_to_text/list_models/embed_text/rerank_documents/get_quota`
+    (community stdio, `npx -y nan-mcp-server@1.3.0`, 120s timeout; 9 tools as of 1.3.0)
+  - `exposure: "direct"` — tools are declared to the model.
   - User `mcp.json` entries with the same name take precedence.
   - `/nan-mcp enable/disable` calls `pi.registerMcpServer()` / `pi.unregisterMcpServer()` directly.
-  - Missing `NAN_API_KEY` at load: web-search server NOT registered (console.warn).
+  - Missing `NAN_API_KEY` at load: media server NOT registered (console.warn).
+  - **`nan-search` was REMOVED in 1.2.1.** NaN's official remote MCP server
+    (`https://api.nan.builders/mcp`) now exposes ZERO tools: `initialize` returns an
+    empty `capabilities.tools` and `tools/list` returns `{"tools":[]}` (verified with a
+    valid key on 2026-10-15), and NaN deleted every MCP mention from its docs (the old
+    `/docs/mcp` redirects to `/docs/agent-setup`). The `web_search` tool no longer
+    exists anywhere in NaN's surface. Users must bring their own `web_search`/fetch MCP
+    server in `mcp.json` (README documents this). `NAN_MCP_TOOLS` is gone with it.
   NaN integration facts remain:
   - pi >=0.99.2 sanitizes MCP tool/namespace names by replacing every character except
-    `[A-Za-z0-9_]` with `"_"` (0.99.0–0.99.1 kept `-`). So `mcp__nan-search__web_search`
-    became `mcp__nan_search__web_search` and `mcp__nan-media__*` became
-    `mcp__nan_media__*`. Server names differing only in `-`/`_` now collide
-    (`nan-search` and `nan-media` do not collide, they differ in more than one character).
+    `[A-Za-z0-9_]` with `"_"` (0.99.0–0.99.1 kept `-`). So `mcp__nan-media__*` keeps its
+    underscore form from 0.99.2 onward. (The removed `nan-search` server used to
+    demonstrate the hyphen→underscore rename; do not rely on it.)
   - pi 0.99.2+/1.0 accept `McpServerConfig.description` (system-prompt listing plus
     tool-search ranking); `validateMcpServerConfig` in 0.99.0–0.99.1 ignores unknown
     keys, so passing `description` stays compatible.
   - NaN's official remote MCP server: `https://api.nan.builders/mcp` (host
     root, NOT /v1; JSON-RPC 2.0 over streamable HTTP, stateless; same `sk-`
     key, shared rate limit/quota). Spec: https://nan.builders/openapi.json
-    (tag "MCP"). Currently exposes `web_search`.
+    (tag "MCP"). **Currently exposes no tools** (see the removal note above).
   - Community `nan-mcp-server` (https://github.com/luciferfran/nan-mcp-server):
-    stdio MCP server, version-pinned via NAN_MEDIA_MCP_VERSION (default 1.1.2)
-    or full command override via NAN_MEDIA_MCP_COMMAND. Tools (1.1.2): generate_image,
+    stdio MCP server, version-pinned via NAN_MEDIA_MCP_VERSION (default 1.3.0)
+    or full command override via NAN_MEDIA_MCP_COMMAND. Tools (1.3.0): generate_image,
     edit_image, text_to_speech, list_voices, speech_to_text, list_models, embed_text,
-    rerank_documents.
+    rerank_documents, get_quota.
   - 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.
@@ -293,11 +320,48 @@ Since 1.0.0 the package version **aligns its MAJOR.MINOR with the pi release lin
   `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`.
-- **pi 1.0.0 / pi-ai 1.0.0 compat** (verified 2026-10-01): the peer range is now
-  `">=0.99.0 <2"` (widened from `">=0.99.0 <1"`); the pi-ai 1.0.0 index/compat/types
-  type surfaces are identical to 0.99.1 (the release only adds a `./models` subpath,
-  Anthropic federation env consts, and a z.ai CN overflow pattern); the package's
-  tests and typecheck pass against 1.0.0 unchanged.
+- **`deepseek-v4-flash` reasoning_effort: the docs are stale, the measurement
+  wins** (re-probed live 2026-10-14). The docs claim the parameter is "any value
+  (no effect)"; a three-model probe disproves it — `none` gave **0** reasoning
+  tokens with a full answer on `deepseek-v4-flash`, `mimo-v2.6-flash` and
+  `qwen3.6`, while `low` gave 57 / 22 / 951 and omitting the parameter 63 / 17 /
+  905 (`minimal` on deepseek gave 109). So `none` disables reasoning and every
+  other value leaves it on. The catalog keeps `reasoningEffortValues: ["none"]`
+  and `thinkingLevelMap { off: "none" }`, and `mimo-v2.6-flash` — which the docs
+  called "depth not adjustable" — gains `thinkingLevelMap { off: "none" }` for
+  the same reason. `qwen3.8-flash` stays unmapped: only `none` was sampled for
+  it, so no other level is mapped. Probe: short prompt, `max_tokens: 2048`,
+  streaming with `include_usage`; 10 requests, under 50k tokens.
+- **Reasoning-only stream limit** (https://nan.builders/docs/models
+  #reasoning-only-stream-limit, checked 2026-10-14): NaN closes a turn that
+  produced only reasoning once it passes 45,000 reasoning characters, or after
+  420 s without visible output (600 s once the turn has demonstrably exceeded
+  that character count); the character budget also scales with prompt size
+  (~150,000 headroom + half the prompt, capped at 300,000). The cut is
+  `finish_reason: "length"` on an empty delta plus a final usage chunk marked
+  `estimated: true`, `billed: false` and carrying
+  `nan_truncation: { reason: "reasoning_only_stream" }`.
+  `src/reasoning-only-stream-guard.ts` (issue #21) keys on that marker;
+  earlier comment/message text said "60,000 characters" and was corrected to
+  the documented figures.
+- **pi 1.2.0 / pi-ai 1.2.0 compat** (verified 2026-10-14, the current verified
+  baseline): the peer range stays `">=0.99.0 <2"` (1.2.0 is inside it). The pi-ai
+  1.2.0 index/compat type surface is byte-identical to 1.0.0 (`index.d.ts` diff is
+  empty); the only additions are `KnownProvider` gaining `"azure"` (renamed from
+  `"azure-openai-responses"` in pi 1.0.3 — not used here), a new
+  `"openai-decisions"` classifier API, `SamplingParams`/`SamplingParamsByThinkingLevel`
+  type aliases (fields pi-ai already honored; `models.json`-only), and a new
+  optional `RefreshModelsContext.baseUrl`. `ThinkingLevelMap`, `ImageModel`,
+  `ImageApi`, `OpenAICompletionsCompat`, `createProvider`, `envApiKeyAuth`,
+  `registerMcpServer`/`unregisterMcpServer` and `registerVirtualModel` are all
+  unchanged, and the `thinkingLevelMap.off` branch in `buildRequest` still fires
+  at `api/openai-completions.js` ~line 719. The package's tests (328) and
+  typecheck pass against 1.2.0 unchanged; the upgrade is devDependency-only.
+- **pi 1.0.0 / pi-ai 1.0.0 compat** (verified 2026-10-01): the peer range was
+  widened to `">=0.99.0 <2"` (from `">=0.99.0 <1"`); the pi-ai 1.0.0
+  index/compat/types type surfaces are identical to 0.99.1 (the release only adds
+  a `./models` subpath, Anthropic federation env consts, and a z.ai CN overflow
+  pattern); the package's tests and typecheck pass against 1.0.0 unchanged.
 - **Native image models** (verified 2026-10-01): pi 1.0 lets a provider register
   `ImageModel` entries (`type: "image"`) plus a `Provider.images` implementation map
   keyed by a custom `ImageApi` id (`"nan-images"`); codemode reaches them with

package/README.es.md

@@ -1,11 +1,12 @@
 # @gtrabanco/pi-nan-provider
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-0.11.0-blue)](https://github.com/gtrabanco/pi-nan-provider/releases)
+[![Version](https://img.shields.io/badge/version-1.2.1-blue)](https://github.com/gtrabanco/pi-nan-provider/releases)
+[![Built with NaN](https://nan.builders/badge/built-with-nan-compact.svg)](https://cloud.nan.builders/r/7GK06FX8)
 
-[NaN Builders](https://nan.builders) model provider + MCP nativo para [pi](https://github.com/earendil-works/pi). 
+[NaN Builders](https://cloud.nan.builders/r/7GK06FX8) model provider + MCP nativo para [pi](https://github.com/earendil-works/pi). 
 
-Registra el proveedor `nan` vía `pi.registerProvider()` usando la API OpenAI-compatible de NaN (`https://api.nan.builders/v1`), y registra servidores MCP nativos con `pi.registerMcpServer()`.
+Registra el proveedor `nan` vía `pi.registerProvider()` usando la API OpenAI-compatible de NaN (`https://api.nan.builders/v1`), y registra el servidor MCP de media de la comunidad con `pi.registerMcpServer()`.
 
 ---
 
@@ -101,22 +102,48 @@ Consigue una clave en la [plataforma NaN](https://cloud.nan.builders/r/7GK06FX8)
 
 ## 🔌 MCP nativo
 
-Dado que [pi 0.99.0 incluye un cliente MCP integrado](https://github.com/earendil-works/pi/blob/main/docs/usage.md), este paquete migra sus puentes a MCP nativo (requiere `pi >=0.99, <2` — pi 0.99 hasta 1.0 son compatibles; el rango peer se amplió a `<2` en 0.11.0).
+Dado que [pi 0.99.0 incluye un cliente MCP integrado](https://github.com/earendil-works/pi/blob/main/docs/usage.md), este paquete usa MCP nativo (requiere `pi >=0.99, <2` — pi 0.99 hasta 1.2 son compatibles; el rango peer se amplió a `<2` en 0.11.0).
 
-Ambos puentes están **activados por defecto** (por sesión, visibles en `/mcp`). Usa `/nan-mcp` para gestionarlos.
+El puente de media está **activado por defecto** (por sesión, visible en `/mcp`). Usa `/nan-mcp` para gestionarlo.
 
-> [!TIP]
-> ¿Prefieres configurar los servidores MCP de NaN tú mismo? Desde pi 0.99.2/1.0, un servidor MCP HTTP en el `mcp.json` global puede autenticarse con tu token de `/login nan` en vez de una clave copiada: `{ "auth": { "provider": "nan" } }` (solo en el `mcp.json` global; requiere `https`). El registro integrado de `nan-search` sigue usando `NAN_API_KEY`/la credencial almacenada.
+> [!WARNING]
+> **El servidor MCP remoto oficial de NaN ya no expone ninguna herramienta.** Hasta 1.2.0 este paquete
+> incluía un puente `nan-search` apuntando a `https://api.nan.builders/mcp`, que exponía
+> `web_search`. Ese servidor ahora responde a `initialize` con `capabilities.tools` vacío y a
+> `tools/list` con `{"tools":[]}` — verificado con una clave válida el 2026-10-15 — y NaN eliminó toda
+> mención a MCP de su documentación (la antigua página `/docs/mcp` ahora redirige a `/docs/agent-setup`).
+> El puente se eliminó en **1.2.1** porque registrar un servidor que no expone nada solo produce un
+> servidor sin herramientas en `/mcp`.
+>
+> **Trae tu propio `web_search` y fetch.** Instala un servidor MCP que los proporcione (p. ej. el par
+> `fetch` + `brave-search` de los servidores MCP oficiales, o cualquier otro servidor MCP de
+> búsqueda/fetch) y decláralo en tu `mcp.json` global:
+>
+> ```json
+> {
+>   "mcpServers": {
+>     "fetch": { "command": "uvx", "args": ["mcp-server-fetch"] },
+>     "web-search": {
+>       "command": "npx",
+>       "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+>       "env": { "BRAVE_API_KEY": "tu-clave" }
+>     }
+>   }
+> }
+> ```
+>
+> Vuelve a comprobar `https://api.nan.builders/mcp` periódicamente: si NaN publica herramientas otra
+> vez, este paquete puede restaurar el puente.
 
 ### 🛠️ Comando de Gestión: `/nan-mcp`
 
 | Comando | Efecto |
 | :--- | :--- |
-| `/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. |
+| `/nan-mcp status` | Muestra el estado del puente de media y la resolución de la clave API. |
+| `/nan-mcp enable [target]` | Activa `nan-mcp-server` (persiste). |
+| `/nan-mcp disable [target]` | Lo desactiva 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.
+El puente resuelve la credencial almacenada de `/login nan` (almacenada → env). Si ninguna se resuelve, el servidor 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.
@@ -171,15 +198,7 @@ conector con `pi config` → Built-in extensions → `mcp`.
 
 ---
 
-### 1. Servidor MCP oficial de NaN
-*Puente oficial para herramientas remotas vía [https://api.nan.builders/mcp](https://nan.builders/docs/api).*
-
-- **`mcp__nan_search__web_search(query, ...)`**: Realiza búsquedas web a través del gateway de NaN.
-  > pi 0.99.0–0.99.1 usaba la forma con guiones (`mcp__nan-search__web_search`); pi 0.99.2+ sanitiza
-  > los nombres de herramientas a solo `[A-Za-z0-9_]`, así que los guiones se convirtieron en
-  > guiones bajos. La forma con guiones bajos aplica desde 0.99.2 hasta pi 1.0.
-
-### 2. Servidor MCP de Media (Comunidad)
+### Servidor MCP de Media (Comunidad)
 *Conecta [`nan-mcp-server`](https://github.com/luciferfran/nan-mcp-server) mediante un cliente stdio local mínimo.*
 
 - **Por sesión**: El servidor se conecta al registrarse (eager). Aparece en `/mcp` con fuente "extension".
@@ -195,21 +214,20 @@ conector con `pi config` → Built-in extensions → `mcp`.
 | `mcp__nan_media__list_models` | Listar los ids de modelos que alcanza la key |
 | `mcp__nan_media__embed_text` | Embeddings de texto (qwen3-embedding) |
 | `mcp__nan_media__rerank_documents` | Reordenación de documentos (Qwen3-Reranker) |
+| `mcp__nan_media__get_quota` | Cuota de tokens por modelo (usado / tope / restante / reinicio) |
 
-> pi 0.99.0–0.99.1 usaba las formas con guiones (`mcp__nan-search__web_search`,
-> `mcp__nan-media__*`); pi 0.99.2+ sanitiza los nombres de herramientas a solo
-> `[A-Za-z0-9_]`, así que los guiones se convirtieron en guiones bajos. La forma
-> con guiones bajos aplica desde 0.99.2 hasta pi 1.0.
+> pi 0.99.0–0.99.1 usaba la forma con guiones (`mcp__nan-media__*`); pi 0.99.2+ sanitiza los
+> nombres de herramientas a solo `[A-Za-z0-9_]`, así que los guiones se convirtieron en guiones
+> bajos. La forma con guiones bajos aplica desde 0.99.2 hasta pi 1.2.
 
 #### 🔧 Configuración del Puente de Media
 
 | Variable | Por defecto | Descripción |
 | :--- | :--- | :--- |
 | `NAN_MEDIA_MCP` | — | Override por sesión (`0` o `false` para desactivar). |
-| `NAN_MEDIA_MCP_VERSION` | `1.1.2` | Versión del servidor fijada (recomendado). |
+| `NAN_MEDIA_MCP_VERSION` | `1.3.0` | Versión del servidor fijada (recomendado). |
 | `NAN_MEDIA_MCP_COMMAND` | — | Override del comando personalizado. |
 | `NAN_MEDIA_MCP_TIMEOUT_MS` | `120000` | Timeout por llamada. |
-| `NAN_MCP_TOOLS` | — | Override para el puente oficial (`0` para desactivar). |
 
 #### 🤖 Detección Automática de Actualizaciones
 
@@ -330,10 +348,14 @@ Modelos de chat:
 | :--- | :--- | :--- | :--- | :---: |
 | `qwen3.6` | 262,144 | 65,536 | texto, imagen | ✅ |
 | `gemma4` | 262,144 | 32,768 | texto, imagen | ✅ |
-| `deepseek-v4-flash` | 1,000,000 | 384,000 | texto, imagen | ✅ |
+| `deepseek-v4-flash` | 1,048,576 | 32,768* | texto, imagen | ✅ |
 | `mimo-v2.6-flash` | 1,048,576 | 131,072 | texto, imagen | ✅ |
-| `glm5.3-flash` | 1,000,000 | 131,072 | texto, imagen | ✅ |
-| `qwen3.8-flash` | 262,144 | 131,072 | texto, imagen | ✅ |
+| `glm5.3-flash` | 1,048,576 | 131,072 | texto, imagen | ✅ |
+| `qwen3.8-flash` | 1,048,576 | 131,072 | texto, imagen | ✅ |
+
+> Las ventanas de la tabla son las **documentadas** en [los docs de NaN](https://nan.builders/docs/models) (comprobado 2026-10-14), que son la fuente de verdad; models.dev es un espejo que un humano actualiza más tarde y puede ir por detrás. `glm5.3` (tier premium, fuera de la tabla estática) es 1,048,576 / 131,072 con entrada texto+imagen cuando una clave premium lo descubre en vivo.
+>
+> `*` El límite de salida de 32,768 en `deepseek-v4-flash` es el techo de los docs oficiales de NaN para pi (https://nan.builders/docs/pi, "the same set the NaN CLI writes", issue #20, 2026-10-02); models.dev sigue listando 384,000, pero la pasarela rechaza `max_tokens` por encima de ~256k con 403.
 
 > [!NOTE]
 > **Techo práctico con caché de prompt fría (issue #18).** Las ventanas de contexto de la tabla son las ventanas reales de los modelos, pero el borde de api.nan.builders (Cloudflare) aborta las respuestas que superan su Proxy Read Timeout de 120 s. Medido con peticiones frías directas (relleno único, sin caché de prompt; 2026-10-01): 208.036 tokens (~960 KB de cuerpo) respondió en 12,9 s mientras que ~220k y ~286k tokens devolvieron **HTTP 524 `origin_response_timeout`** a los ~126 s; los mismos tamaños con caché cálida responden en ~10 s. El techo práctico para peticiones frías queda por tanto muy por debajo de las ventanas declaradas. Desde 1.0.0 el provider reclasifica un 524 en una petición estimada por encima de 200.000 tokens (`NAN_COLD_CACHE_CEILING_TOKENS`) como desbordamiento de contexto para que pi compacte y reintente en vez de quedarse colgado; un 524 en una petición menor se deja intacto (timeout transitorio genuino).
@@ -363,11 +385,12 @@ El parámetro `reasoning_effort` de NaN controla cuánto piensa el modelo antes
 | :--- | :--- | :--- |
 | `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 |
+| `deepseek-v4-flash` | `none` (el catálogo declara ["none"]) | `none` deshabilita el razonamiento (0 tokens de razonamiento, respuesta completa); cualquier otro valor — incluido `minimal` y omitir el parámetro — lo deja ENCENDIDO (57 / 63 / 109 tokens de razonamiento), así que el catálogo solo declara `none`. Re-sondado en vivo 2026-10-14: los docs de NaN afirman "any value (no effect)", pero gana la medición. `thinking: "off"` envía `reasoning_effort: "none"` automáticamente vía el `thinkingLevelMap` del catálogo — sin él el modelo se descontrola hasta `finish_reason: "length"` sin respuesta (issue #16) |
+| `qwen3.8-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 este modelo no ajusta |
+| `mimo-v2.6-flash` | `none` | Los docs lo llamaban "profundidad no ajustable", pero el gateway en vivo (2026-10-14) muestra que `none` da 0 tokens de razonamiento con respuesta completa mientras `low` da 22 y omitirlo 17 — así que `thinking: "off"` envía `reasoning_effort: "none"` vía el `thinkingLevelMap` del catálogo |
 
 > [!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).
+> `maxTokens` NO limita la fase de razonamiento en los modelos de NaN. La fase de razonamiento corre hasta completarse (o se corta en el límite de stream solo-razonamiento de NaN: 45.000 caracteres de razonamiento, o 420 s sin salida visible) 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
 
@@ -378,4 +401,4 @@ bun test                  # Ejecutar todos los tests
 bun run typecheck         # Ejecutar typechecking
 ```
 
-*Las versiones siguen semver estricto. CI publica automáticamente al hacer merge a `main`.*
+*Las versiones siguen semver estricto. CI publica automáticamente al hacer merge a `main`.*

package/README.md

@@ -1,11 +1,12 @@
 # @gtrabanco/pi-nan-provider
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-0.11.0-blue)](https://github.com/gtrabanco/pi-nan-provider/releases)
+[![Version](https://img.shields.io/badge/version-1.2.1-blue)](https://github.com/gtrabanco/pi-nan-provider/releases)
+[![Built with NaN](https://nan.builders/badge/built-with-nan-compact.svg)](https://cloud.nan.builders/r/7GK06FX8)
 
-[NaN Builders](https://nan.builders) model provider + native MCP servers for [pi](https://github.com/earendil-works/pi). 
+[NaN Builders](https://cloud.nan.builders/r/7GK06FX8) model provider + a native MCP server for [pi](https://github.com/earendil-works/pi). 
 
-Registers the `nan` provider via `pi.registerProvider()` using NaN's OpenAI-compatible API (`https://api.nan.builders/v1`), and registers MCP servers via pi's native `pi.registerMcpServer()`.
+Registers the `nan` provider via `pi.registerProvider()` using NaN's OpenAI-compatible API (`https://api.nan.builders/v1`), and registers the community media MCP server via pi's native `pi.registerMcpServer()`.
 
 ---
 
@@ -99,24 +100,50 @@ You can override any model's `compat` per-model in `~/.pi/agent/models.json` (pi
 
 Get a key from the [NaN platform](https://cloud.nan.builders/r/7GK06FX8) (user settings → API Keys; referral link).
 
-## 🔌 Native MCP Servers
+## 🔌 Native MCP Server
 
-Since [pi 0.99.0 ships a built-in MCP client](https://github.com/earendil-works/pi/blob/main/docs/usage.md), this package migrates its bridges to native MCP (requires `pi >=0.99, <2` — pi 0.99 through 1.0 are supported; the peer range was widened to `<2` in 0.11.0).
+Since [pi 0.99.0 ships a built-in MCP client](https://github.com/earendil-works/pi/blob/main/docs/usage.md), this package bridges to native MCP (requires `pi >=0.99, <2` — pi 0.99 through 1.2 are supported; the peer range was widened to `<2` in 0.11.0).
 
-Both bridges are **enabled by default** (session-scoped, visible in `/mcp`). Use `/nan-mcp` to manage them.
+The media bridge is **enabled by default** (session-scoped, visible in `/mcp`). Use `/nan-mcp` to manage it.
 
-> [!TIP]
-> Prefer to configure NaN's MCP servers yourself? Since pi 0.99.2/1.0 an HTTP MCP server in the global `mcp.json` can authenticate with your `/login nan` token instead of a copied key: `{ "auth": { "provider": "nan" } }` (global `mcp.json` only; `https` required). The bundled `nan-search` registration keeps using `NAN_API_KEY`/the stored credential.
+> [!WARNING]
+> **NaN's official remote MCP server no longer exposes any tool.** Until 1.2.0 this package shipped a
+> `nan-search` bridge pointing at `https://api.nan.builders/mcp`, which exposed
+> `web_search`. That server now answers `initialize` with an empty `capabilities.tools` and
+> `tools/list` with `{"tools":[]}` — verified with a valid key on 2026-10-15 — and NaN removed every
+> MCP mention from its documentation (the old `/docs/mcp` page now redirects to `/docs/agent-setup`).
+> The bridge was removed in **1.2.1** because registering a server that exposes nothing only produces
+> a tool-less server in `/mcp`.
+>
+> **Bring your own `web_search` and fetch.** Install an MCP server that provides them (e.g. the
+> `fetch` + `brave-search` pair for the official MCP servers, or any other search/fetch MCP server)
+> and declare it in your global `mcp.json`:
+>
+> ```json
+> {
+>   "mcpServers": {
+>     "fetch": { "command": "uvx", "args": ["mcp-server-fetch"] },
+>     "web-search": {
+>       "command": "npx",
+>       "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+>       "env": { "BRAVE_API_KEY": "your-key" }
+>     }
+>   }
+> }
+> ```
+>
+> Re-check `https://api.nan.builders/mcp` periodically: if NaN publishes tools again, this package can
+> restore the bridge.
 
 ### 🛠️ Management Command: `/nan-mcp`
 
 | Command | Effect |
 | :--- | :--- |
-| `/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. |
+| `/nan-mcp status` | Shows the media bridge state and API key resolution. |
+| `/nan-mcp enable [target]` | Enables `nan-mcp-server` (persisted). |
+| `/nan-mcp disable [target]` | Disables it 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.
+The bridge resolves the stored `/login nan` credential (stored → env). If neither resolves, the server 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.
@@ -168,15 +195,7 @@ registering a server that can never connect. To get MCP in the CLI, enable the c
 
 ---
 
-### 1. Official NaN MCP Server
-*Official remote MCP server registered natively via `pi.registerMcpServer()`.*
-
-- **`mcp__nan_search__web_search(query, ...)`**: Performs web searches through NaN's gateway.
-  > pi 0.99.0–0.99.1 used the hyphenated form (`mcp__nan-search__web_search`); pi 0.99.2+ sanitizes
-  > tool names to `[A-Za-z0-9_]` only, so hyphens became underscores. The underscore form applies
-  > from 0.99.2 onward through pi 1.0.
-
-### 2. Community Media MCP Server
+### Community Media MCP Server
 *Bridges [`nan-mcp-server`](https://github.com/luciferfran/nan-mcp-server) via a minimal local stdio client.*
 
 - **Session-scoped**: The server connects at registration time (eager). Appears in `/mcp` with source "extension".
@@ -192,21 +211,20 @@ registering a server that can never connect. To get MCP in the CLI, enable the c
 | `mcp__nan_media__list_models` | List the NaN model ids the key can reach |
 | `mcp__nan_media__embed_text` | Text embeddings (qwen3-embedding) |
 | `mcp__nan_media__rerank_documents` | Document reranking (Qwen3-Reranker) |
+| `mcp__nan_media__get_quota` | Per-model token quota (used / cap / remaining / reset) |
 
-> pi 0.99.0–0.99.1 used the hyphenated forms (`mcp__nan-search__web_search`,
-> `mcp__nan-media__*`); pi 0.99.2+ sanitizes tool names to `[A-Za-z0-9_]` only,
-> so hyphens became underscores. The underscore form applies from 0.99.2 onward
-> through pi 1.0.
+> pi 0.99.0–0.99.1 used the hyphenated form (`mcp__nan-media__*`); pi 0.99.2+ sanitizes tool
+> names to `[A-Za-z0-9_]` only, so hyphens became underscores. The underscore form applies from
+> 0.99.2 onward through pi 1.2.
 
 #### 🔧 Media Bridge Configuration
 
 | Variable | Default | Description |
 | :--- | :--- | :--- |
 | `NAN_MEDIA_MCP` | — | Per-session override (`0` or `false` to disable). |
-| `NAN_MEDIA_MCP_VERSION` | `1.1.2` | Pinned server version (recommended). |
+| `NAN_MEDIA_MCP_VERSION` | `1.3.0` | Pinned server version (recommended). |
 | `NAN_MEDIA_MCP_COMMAND` | — | Custom command override. |
 | `NAN_MEDIA_MCP_TIMEOUT_MS` | `120000` | Per-call timeout. |
-| `NAN_MCP_TOOLS` | — | Override for the official bridge (`0` to disable). |
 
 #### 🤖 Automated Update Detection
 
@@ -327,12 +345,14 @@ Chat models:
 | :--- | :--- | :--- | :--- | :---: |
 | `qwen3.6` | 262,144 | 65,536 | text, image | ✅ |
 | `gemma4` | 262,144 | 32,768 | text, image | ✅ |
-| `deepseek-v4-flash` | 1,000,000 | 32,768* | text, image | ✅ |
+| `deepseek-v4-flash` | 1,048,576 | 32,768* | text, image | ✅ |
 | `mimo-v2.6-flash` | 1,048,576 | 131,072 | text, image | ✅ |
-| `glm5.3-flash` | 1,000,000 | 131,072 | text, image | ✅ |
-| `qwen3.8-flash` | 262,144 | 131,072 | text, image | ✅ |
+| `glm5.3-flash` | 1,048,576 | 131,072 | text, image | ✅ |
+| `qwen3.8-flash` | 1,048,576 | 131,072 | text, image | ✅ |
 
 > [!NOTE]
+> Context windows above are the **documented** windows from [the NaN docs](https://nan.builders/docs/models) (checked 2026-10-14), which are the source of truth; models.dev is a downstream mirror a human updates later and may lag. `glm5.3` (premium tier, not in the static table above) is 1,048,576 / 131,072 with text+image input when a premium key discovers it live.
+>
 > `*` deepseek-v4-flash max output 32,768 is the ceiling from the official NaN pi docs (https://nan.builders/docs/pi, "the same set the NaN CLI writes", issue #20, 2026-10-02); models.dev still lists 384,000 but the gateway rejects `max_tokens` above ~256k with 403.
 >
 > **Cold prompt cache practical ceiling (issue #18).** The context windows above are the models' real windows, but the api.nan.builders edge (Cloudflare) aborts responses past its 120 s Proxy Read Timeout. Measured with direct cold requests (unique filler, no prompt cache; 2026-10-01): 208,036 tokens (~960 KB body) answered in 12.9 s while ~220k and ~286k tokens returned **HTTP 524 `origin_response_timeout`** at ~126 s; the same sizes with a warm prompt cache answer in ~10 s. The practical ceiling for cold requests is therefore well below the declared windows. Since 1.0.0 the provider reclassifies a 524 on an estimated over-200,000-token request (`NAN_COLD_CACHE_CEILING_TOKENS`) as a context overflow so pi compacts and retries instead of wedging; a 524 on a smaller request is left alone (genuine transient timeout).
@@ -360,10 +380,11 @@ NaN's `reasoning_effort` parameter controls how much the model thinks before ans
 | :--- | :--- | :--- |
 | `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 |
+| `deepseek-v4-flash` | `none` (catalog declares ["none"]) | `none` disables reasoning (0 reasoning tokens, a full answer); every other value — including `minimal` and omitting the parameter — leaves it ON (57 / 63 / 109 reasoning tokens), so the catalog declares only `none`. Re-probed live 2026-10-14: the NaN docs claim "any value (no effect)", but the measurement wins. `thinking: "off"` sends `reasoning_effort: "none"` automatically via the catalog's `thinkingLevelMap` — without it the model runs away to `finish_reason: "length"` with no answer (issue #16) |
+| `qwen3.8-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 this model doesn't adjust |
+| `mimo-v2.6-flash` | `none` | The docs called this "depth not adjustable", but the live gateway (2026-10-14) shows `none` gives 0 reasoning tokens with a full answer while `low` gives 22 and omitting the parameter 17 — so `thinking: "off"` sends `reasoning_effort: "none"` via the catalog's `thinkingLevelMap` |
 > [!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).
+> `maxTokens` does NOT bound the reasoning phase on NaN models. The reasoning phase runs to completion (or is cut at NaN's reasoning-only stream limit: 45,000 reasoning characters, or 420 s without visible output) 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).
 
 
 ---
@@ -377,4 +398,4 @@ bun test                  # Run all tests
 bun run typecheck         # Run typechecking
 ```
 
-*Releases follow strict semver. CI publishes automatically on merge to `main`.*
+*Releases follow strict semver. CI publishes automatically on merge to `main`.*

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@gtrabanco/pi-nan-provider",
-	"version": "1.0.1",
-	"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)",
+	"version": "1.2.1",
+	"description": "NaN Builders (api.nan.builders) model provider for pi - OpenAI-compatible registration with a models.dev-generated fallback, tier-aware live catalog, and an optional community media MCP bridge",
 	"keywords": [
 		"pi",
 		"pi-package",
@@ -46,8 +46,8 @@
 		"@earendil-works/pi-coding-agent": ">=0.99.0 <2"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-ai": "1.0.0",
-		"@earendil-works/pi-coding-agent": "1.0.0",
+		"@earendil-works/pi-ai": "1.2.0",
+		"@earendil-works/pi-coding-agent": "1.2.0",
 		"@types/bun": "1.4",
 		"typescript": "7"
 	},

package/scripts/check-nan-mcp-server.ts

@@ -318,7 +318,7 @@ export function renderIssueBody(report: NanMcpServerCheckReport): string {
 	}
 	lines.push("### To bump");
 	lines.push(
-		`1. Edit \`DEFAULT_NAN_MEDIA_MCP_VERSION\` in \`src/mcp/nan-media.ts\` from \`${report.pinnedVersion}\` to \`${report.latestVersion}\`.`,
+		`1. Edit \`DEFAULT_NAN_MEDIA_MCP_VERSION\` in \`src/mcp/media-server.ts\` from \`${report.pinnedVersion}\` to \`${report.latestVersion}\`.`,
 	);
 	lines.push("2. Run \`bun test && bun run typecheck\`.");
 	lines.push(

package/scripts/generate-models.ts

@@ -79,12 +79,10 @@ const PI_SUPPORTED_INPUT = new Set(["text", "image"]);
  * (shared with test/generated-catalog.test.ts, which pins that every
  * override lands on the generated entry with its provenance note).
  * Capability divergences from models.dev are recorded there, never here.
- * MANUAL_NOTES adds provenance-only notes to otherwise-untouched entries.
+ * MANUAL_NOTES adds provenance-only notes to otherwise-untouched entries
+ * (currently empty; per-model corrections live in MANUAL_OVERRIDES).
  */
-const MANUAL_NOTES: Record<string, string> = {
-	"qwen3.8-flash":
-		"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).",
-};
+const MANUAL_NOTES: Record<string, string> = {};
 
 /**
  * Models the provider has removed but that models.dev may still list.