@gtrabanco/pi-nan-provider 0.10.3 → 1.0.1

package/AGENTS.md

@@ -65,13 +65,15 @@ factory in `src/provider-factory.ts`. A second provider-specific file is a smell
 refactor back to the factory and add a config entry in `src/providers.ts` instead.
 The `factory is shared` test in `test/provider-factory.test.ts` guards this contract.
 
-## Version policy (strict semver)
+## Version policy (strict semver, pi-aligned scheme)
 
 Every PR that changes code MUST bump `package.json` version in the same PR; CI publishes only when the version differs from npm.
 
-- **PATCH** (`0.1.z`): bug fixes, docs, comment-only changes, catalog regeneration with identical values.
-- **MINOR** (`0.x.0`): new features — new provider entries, new MCP tools, new env vars/config options, and (while `0.x`) breaking changes, each breaking change called out explicitly in the PR/changelog.
-- **MAJOR** (`x.0.0`): breaking changes once `1.0.0` is reached.
+Since 1.0.0 the package version **aligns its MAJOR.MINOR with the pi release line the release is verified against** (pi 1.0.0 → package `1.0.x`; when pi ships 1.1.0, the next package release takes `1.1.0` even if it only carries fixes). The version marks the verified baseline, not the full support range — the npm `peerDependencies` range stays independent and usually wider.
+
+- **PATCH** (`1.0.z`): bug fixes, docs, comment-only changes, catalog regeneration with identical values — the usual release cadence between pi minor releases.
+- **MINOR** (`1.x.0`): reserved for tracking pi's minor releases (and may carry new features — new provider entries, new MCP tools, new env vars/config options).
+- **MAJOR** (`x.0.0`): breaking changes, and re-alignment if pi ever ships a new major.
 - Never reuse a published version; never publish with failing tests (CI gates publish on tests + typecheck).
 - The npm registry is the source of truth for "published"; `.github/workflows/publish.yml` compares `package.json` against `npm view` and publishes only on difference.
 
@@ -247,23 +249,32 @@ Every PR that changes code MUST bump `package.json` version in the same PR; CI p
 - Since 0.10.0, this package uses native MCP via `pi.registerMcpServer()`.
   Both servers are session-scoped, visible in `/mcp` with source "extension".
   Server names and tool IDs:
-  - `nan-search` → tools: `mcp__nan-search__web_search`
+  - `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`
-    (community stdio, `npx -y nan-mcp-server@1.1.2`, 120s timeout)
+  - `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.
   - 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).
   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).
+  - 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`.
   - 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: generate_image,
-    edit_image, text_to_speech, list_voices, speech_to_text.
+    or full command override via NAN_MEDIA_MCP_COMMAND. Tools (1.1.2): generate_image,
+    edit_image, text_to_speech, list_voices, speech_to_text, list_models, embed_text,
+    rerank_documents.
   - 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.
@@ -282,3 +293,51 @@ Every PR that changes code MUST bump `package.json` version in the same PR; CI p
   `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.
+- **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
+  `models.generateImages()` / `getModelOfType("image", provider, id)`, extensions with
+  `ctx.modelRegistry.generateImages()`. pi-ai never applies `filterModels` to
+  non-chat models, so image availability is not tier-filtered by the live `/models`
+  list — the 403 at call time is the tier signal. NaN endpoints and quotas are
+  documented in the package's image-model notes.
+- **Cold-cache 524 wedge: measured practical ceiling + two-threshold classifier**
+  (issue #18, measured 2026-10-01 with direct cold curl probes, no pi in the
+  loop): api.nan.builders sits behind Cloudflare with a 120 s Proxy Read
+  Timeout. A COLD prompt of 208,036 tokens (~960 KB body) answered in 12.9 s;
+  ~220k and ~286k tokens returned HTTP 524 `origin_response_timeout` at ~126 s
+  (JSON body or Cloudflare HTML page). Warm (cached) requests of the same size
+  answer in ~10 s. pi-ai (0.99.x–1.0.0) lists "524" in
+  `RETRYABLE_PROVIDER_ERROR_PATTERN` (retrying an identical cold payload always
+  fails) and `isContextOverflow()` matches nothing → the session wedges.
+  `src/context-overflow-classifier.ts` therefore has TWO independent
+  thresholds: the 400 branch (issue #3) keys on the model's `contextWindow`;
+  the 524 branch keys on `NAN_COLD_CACHE_CEILING_TOKENS` = 200,000 ONLY
+  (conservative midpoint below the last-working 208k measurement) — the
+  declared catalog windows are NOT reduced. A 524 below the ceiling stays a
+  transient retryable error. Compaction is a single pass with no hard-truncation
+  fallback in pi, so the rewrite rescues sessions that one compaction can bring
+  under the ceiling; far-over sessions still wedge (same limit as the #3 path).
+- **Stale persisted catalog shadowing (issue #19, verified on pi-ai/pi 1.0.0):**
+  pi-ai's `createProvider`-built `refreshModels` restores
+  `context.stored.models` VERBATIM in the cache-only phase
+  (`dynamicModels = restored`, a closure variable unreachable from outside) and
+  `currentModels()` lets a dynamic entry REPLACE the static baseline entry with
+  the same id+type — so a `models-store.json` entry written by an older package
+  version (e.g. without `thinkingLevelMap`) shadows the newer generated
+  capability data whenever its `checkedAt` is fresh; `ModelsStoreEntry` has no
+  version/staleness signal. pi's `ModelsImpl` resolves models exclusively via
+  the provider object's `getModels()`/`getAllModels()`. Fix: `src/provider-factory.ts`
+  wraps both accessors (`withStaleCatalogOverlay`) to apply generated-catalog
+  capability data at READ time (chat ids from the generated catalog, image ids
+  from `baselineImageModels`) — the store decides which ids exist, the
+  generated catalog decides capability data; uncatalogued ids (live-only
+  `glm5.3`, ghosts) pass through untouched. `refreshModels` is NOT overridden:
+  the network phase already persists correct merged data. Option (a) of the
+  reporter (version-stamping persisted entries) is NOT implementable
+  provider-side: the store write path belongs to pi-ai.

package/README.es.md

@@ -1,7 +1,7 @@
 # @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.10.0-blue)](https://github.com/gtrabanco/pi-nan-provider/releases)
+[![Version](https://img.shields.io/badge/version-0.11.0-blue)](https://github.com/gtrabanco/pi-nan-provider/releases)
 
 [NaN Builders](https://nan.builders) model provider + MCP nativo para [pi](https://github.com/earendil-works/pi). 
 
@@ -101,10 +101,13 @@ 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` — cambio rotundo).
+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).
 
 Ambos puentes están **activados por defecto** (por sesión, visibles en `/mcp`). Usa `/nan-mcp` para gestionarlos.
 
+> [!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.
+
 ### 🛠️ Comando de Gestión: `/nan-mcp`
 
 | Comando | Efecto |
@@ -132,7 +135,7 @@ con un único aviso por sesión, mantiene los registros inactivos y deja que `/n
 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
+### Funciones de pi 0.99-1.0 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
@@ -145,12 +148,36 @@ conector con `pi config` → Built-in extensions → `mcp`.
   endpoints de embedding/rerank/audio/imagen), así que este proveedor no registra modelos
   `type: "classifier"`.
 
+- **Modelos de imagen nativos de NaN** — flux-2-klein (text-to-image + image-to-image) y
+  qwen-image-2.1 (text-to-image) se registran como modelos de imagen de pi (`type: "image"`,
+  api `"nan-images"`). No aparecen en `/model`; se acceden desde codemode
+  con `models.generateImages(model, { input })` o desde extensiones con
+  `ctx.modelRegistry.generateImages()`:
+
+  ```
+  const painter = await models.getModelOfType("image", "nan", "flux-2-klein")
+  const result = await models.generateImages(painter, { input: [{ type: "text", text: "A red fox in the snow, watercolor" }] })
+  if (result.stopReason !== "stop") return result.errorMessage
+  for (const block of result.output) if (block.type === "image") image(block)
+  ```
+
+  Ambos modelos necesitan el tier de membresía "inference" (403 de lo contrario); los endpoints
+  de imagen tienen su propio límite de tasa separado del chat (20 peticiones/min, 100
+  peticiones/mes compartido entre los dos modelos) y no consumen el presupuesto de tokens del
+  chat. [docs de NaN](https://nan.builders/docs/models) y [OpenAPI](https://nan.builders/openapi.json)
+  (comprobado 2026-10-01). El servidor MCP nan-media de la comunidad ya ofrece la misma
+  generación y edición como herramientas MCP, mientras que los modelos de imagen nativos permiten
+  que codemode y las extensiones los llamen directamente.
+
 ---
 
 ### 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.
+- **`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)
 *Conecta [`nan-mcp-server`](https://github.com/luciferfran/nan-mcp-server) mediante un cliente stdio local mínimo.*
@@ -160,11 +187,19 @@ conector con `pi config` → Built-in extensions → `mcp`.
 
 | Herramienta | Propósito |
 | :--- | :--- |
-| `mcp__nan-media__generate_image` | Generación de imágenes (flux-2-klein) |
-| `mcp__nan-media__edit_image` | Edición imagen→imagen (flux-2-klein) |
-| `mcp__nan-media__text_to_speech` | Síntesis de audio (kokoro) |
-| `mcp__nan-media__list_voices` | Listar voces disponibles |
-| `mcp__nan-media__speech_to_text` | Transcripción de audio (whisper) |
+| `mcp__nan_media__generate_image` | Generación de imágenes (flux-2-klein) |
+| `mcp__nan_media__edit_image` | Edición imagen→imagen (flux-2-klein) |
+| `mcp__nan_media__text_to_speech` | Síntesis de audio (kokoro) |
+| `mcp__nan_media__list_voices` | Listar voces disponibles |
+| `mcp__nan_media__speech_to_text` | Transcripción de audio (whisper) |
+| `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) |
+
+> 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.
 
 #### 🔧 Configuración del Puente de Media
 
@@ -289,6 +324,8 @@ Los errores siguen siendo accionables: `401` → ejecuta `/login nan` o corrige
 
 Catálogo base (verificado contra [docs de NaN](https://nan.builders/docs/models) y [OpenAPI](https://nan.builders/openapi.json)).
 
+Modelos de chat:
+
 | Modelo | Contexto | Máx. Salida | Entrada | Razonamiento |
 | :--- | :--- | :--- | :--- | :---: |
 | `qwen3.6` | 262,144 | 65,536 | texto, imagen | ✅ |
@@ -298,6 +335,17 @@ Catálogo base (verificado contra [docs de NaN](https://nan.builders/docs/models
 | `glm5.3-flash` | 1,000,000 | 131,072 | texto, imagen | ✅ |
 | `qwen3.8-flash` | 262,144 | 131,072 | texto, imagen | ✅ |
 
+> [!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).
+
+Modelos de imagen no-chat (disponibles vía `models.generateImages()` /
+`getModelOfType("image", …)`, no a través de `/model`):
+
+| Modelo | Entrada | Propósito |
+| :--- | :--- | :--- |
+| `flux-2-klein` | texto, imagen | Text-to-image + image-to-image |
+| `qwen-image-2.1` | texto | Text-to-image |
+
 > [!NOTE]  
 > `mimo-v2.6-flash` está servido por NaN y desde el 2026-09-29 aparece también en models.dev (proveedor `nan`); la entrada manual que lo sostenía se conserva como fallback y su nota de procedencia sigue unida a la entrada generada.
 >

package/README.md

@@ -1,7 +1,7 @@
 # @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.10.0-blue)](https://github.com/gtrabanco/pi-nan-provider/releases)
+[![Version](https://img.shields.io/badge/version-0.11.0-blue)](https://github.com/gtrabanco/pi-nan-provider/releases)
 
 [NaN Builders](https://nan.builders) model provider + native MCP servers for [pi](https://github.com/earendil-works/pi). 
 
@@ -101,10 +101,13 @@ Get a key from the [NaN platform](https://cloud.nan.builders/r/7GK06FX8) (user s
 
 ## 🔌 Native MCP Servers
 
-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` — breaking).
+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).
 
 Both bridges are **enabled by default** (session-scoped, visible in `/mcp`). Use `/nan-mcp` to manage them.
 
+> [!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.
+
 ### 🛠️ Management Command: `/nan-mcp`
 
 | Command | Effect |
@@ -131,7 +134,7 @@ per session, keeps the registrations idle, and lets `/nan-mcp enable` persist th
 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
+### pi 0.99-1.0 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
@@ -142,12 +145,36 @@ registering a server that can never connect. To get MCP in the CLI, enable the c
 - **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.
 
+- **Native NaN image models** — flux-2-klein (text-to-image + image-to-image) and
+  qwen-image-2.1 (text-to-image) are registered as pi image models (`type: "image"`,
+  api `"nan-images"`). They do not appear in `/model`; they are reached through codemode
+  with `models.generateImages(model, { input })` or from extensions with
+  `ctx.modelRegistry.generateImages()`:
+
+  ```
+  const painter = await models.getModelOfType("image", "nan", "flux-2-klein")
+  const result = await models.generateImages(painter, { input: [{ type: "text", text: "A red fox in the snow, watercolor" }] })
+  if (result.stopReason !== "stop") return result.errorMessage
+  for (const block of result.output) if (block.type === "image") image(block)
+  ```
+
+  Both models need the "inference" membership tier (403 otherwise); the image endpoints
+  are rate-limited separately from chat (20 requests/min, 100 requests/month shared
+  between the two models) and do not consume the chat token budget.
+  [NaN docs](https://nan.builders/docs/models) and [OpenAPI](https://nan.builders/openapi.json)
+  (checked 2026-10-01). The community nan-media MCP server already offers the same
+  generation and editing as MCP tools, while the native image models let codemode and
+  extensions call them directly.
+
 ---
 
 ### 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.
+- **`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
 *Bridges [`nan-mcp-server`](https://github.com/luciferfran/nan-mcp-server) via a minimal local stdio client.*
@@ -157,11 +184,19 @@ registering a server that can never connect. To get MCP in the CLI, enable the c
 
 | Tool | Purpose |
 | :--- | :--- |
-| `mcp__nan-media__generate_image` | Image generation (flux-2-klein) |
-| `mcp__nan-media__edit_image` | Image-to-image editing (flux-2-klein) |
-| `mcp__nan-media__text_to_speech` | Audio synthesis (kokoro) |
-| `mcp__nan-media__list_voices` | List available voices |
-| `mcp__nan-media__speech_to_text` | Audio transcription (whisper) |
+| `mcp__nan_media__generate_image` | Image generation (flux-2-klein) |
+| `mcp__nan_media__edit_image` | Image-to-image editing (flux-2-klein) |
+| `mcp__nan_media__text_to_speech` | Audio synthesis (kokoro) |
+| `mcp__nan_media__list_voices` | List available voices |
+| `mcp__nan_media__speech_to_text` | Audio transcription (whisper) |
+| `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) |
+
+> 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.
 
 #### 🔧 Media Bridge Configuration
 
@@ -286,15 +321,30 @@ Failures stay actionable: `401` → run `/login nan` or fix `NAN_API_KEY`, `404`
 
 Baseline catalog (verified against [NaN docs](https://nan.builders/docs/models) and [OpenAPI](https://nan.builders/openapi.json)).
 
+Chat models:
+
 | Model | Context | Max Output | Input | Reasoning |
 | :--- | :--- | :--- | :--- | :---: |
 | `qwen3.6` | 262,144 | 65,536 | text, image | ✅ |
 | `gemma4` | 262,144 | 32,768 | text, image | ✅ |
-| `deepseek-v4-flash` | 1,000,000 | 384,000 | text, image | ✅ |
+| `deepseek-v4-flash` | 1,000,000 | 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 | ✅ |
 
+> [!NOTE]
+> `*` 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).
+
+Non-chat image models (available through `models.generateImages()` /
+`getModelOfType("image", …)`, not through `/model`):
+
+| Model | Input | Purpose |
+| :--- | :--- | :--- |
+| `flux-2-klein` | text, image | Text-to-image + image-to-image |
+| `qwen-image-2.1` | text | Text-to-image |
+
 > [!NOTE]  
 > `mimo-v2.6-flash` is served by NaN and has been listed by models.dev provider `nan` since 2026-09-29. Before that it entered the catalog through a manual-only entry; that entry is kept as a fallback (re-emitted automatically if models.dev drops the model again) and its provenance note stays attached to the generated entry.
 >

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gtrabanco/pi-nan-provider",
-	"version": "0.10.3",
+	"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)",
 	"keywords": [
 		"pi",
@@ -42,12 +42,12 @@
 		"check-pi-sdk-versions": "node scripts/check-pi-sdk-versions.mjs --report"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-ai": ">=0.99.0 <1",
-		"@earendil-works/pi-coding-agent": ">=0.99.0 <1"
+		"@earendil-works/pi-ai": ">=0.99.0 <2",
+		"@earendil-works/pi-coding-agent": ">=0.99.0 <2"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-ai": "0.99.1",
-		"@earendil-works/pi-coding-agent": "0.99.1",
+		"@earendil-works/pi-ai": "1.0.0",
+		"@earendil-works/pi-coding-agent": "1.0.0",
 		"@types/bun": "1.4",
 		"typescript": "7"
 	},

package/scripts/manual-overrides.ts

@@ -141,10 +141,12 @@ export const MANUAL_ONLY_MODELS: Record<string, ManualModelOverride> = {
 export const MANUAL_OVERRIDES: Record<string, ManualModelOverride> = {
 	"deepseek-v4-flash": {
 		input: ["text", "image"],
+		maxTokens: 32_768,
 		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. " +
+			"maxTokens 32768 per the official NaN pi docs (https://nan.builders/docs/pi, 'the same set the NaN CLI writes', checked 2026-10-02) closing issue #20 — the gateway now rejects max_tokens above ~256k for this model with 403 permission_error (measured 2026-10-02: 256,000 → 200; 262,143 → 403), and the previous models.dev-derived 384000 made every pi request fail since pi-ai sends max_tokens = model.maxTokens when no cap is set. models.dev still lists 384000, so this override pins the documented value. " +
 			"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.",
 	},

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-10-01T10:56:14.717Z
+// Source: https://models.dev/api.json (provider "nan"), fetched 2026-10-02T22:53:40.291Z
 // 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.
@@ -27,7 +27,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"cacheWrite": 0
 		},
 		"contextWindow": 1000000,
-		"maxTokens": 384000,
+		"maxTokens": 32768,
 		"reasoningEffortValues": [
 			"none"
 		],
@@ -43,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=[\"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."
+			"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. maxTokens 32768 per the official NaN pi docs (https://nan.builders/docs/pi, 'the same set the NaN CLI writes', checked 2026-10-02) closing issue #20 — the gateway now rejects max_tokens above ~256k for this model with 403 permission_error (measured 2026-10-02: 256,000 → 200; 262,143 → 403), and the previous models.dev-derived 384000 made every pi request fail since pi-ai sends max_tokens = model.maxTokens when no cap is set. models.dev still lists 384000, so this override pins the documented value. 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",
@@ -455,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-10-01T10:56:14.717Z",
+	fetchedAt: "2026-10-02T22:53:40.291Z",
 	modelCount: 6,
 	models: ["deepseek-v4-flash","gemma4","glm5.3-flash","mimo-v2.6-flash","qwen3.6","qwen3.8-flash"],
 	notes: [
@@ -469,7 +469,7 @@ export const GENERATED_CATALOG_META = {
 	"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=[\"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.",
+	"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. maxTokens 32768 per the official NaN pi docs (https://nan.builders/docs/pi, 'the same set the NaN CLI writes', checked 2026-10-02) closing issue #20 — the gateway now rejects max_tokens above ~256k for this model with 403 permission_error (measured 2026-10-02: 256,000 → 200; 262,143 → 403), and the previous models.dev-derived 384000 made every pi request fail since pi-ai sends max_tokens = model.maxTokens when no cap is set. models.dev still lists 384000, so this override pins the documented value. 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.)",

package/src/commands.ts

@@ -3,9 +3,11 @@
  * package registers:
  *
  * - `nan-search` — the official NaN remote MCP server (api.nan.builders/mcp),
- *   exposing `mcp__nan-search__web_search`. Default: enabled.
+ *   exposing `mcp__nan_search__web_search` (pi >=0.99.2). Default: enabled.
+ *   (pi 0.99.0–0.99.1 used the hyphenated form `mcp__nan-search__web_search`.)
  * - `nan-media` — the community stdio media server (flux-2-klein / kokoro /
- *   whisper), exposing `mcp__nan-media__generate_image` etc. Default: enabled.
+ *   whisper), exposing `mcp__nan_media__generate_image` etc. Default: enabled.
+ *   (pi 0.99.0–0.99.1 used the hyphenated form `mcp__nan-media__*`.)
  *
  * Both are session-scoped native servers (visible in /mcp, source "extension").
  * /nan-mcp enables/disables them via pi.registerMcpServer / pi.unregisterMcpServer,
@@ -74,8 +76,8 @@ function serverName(bridge: BridgeKey): string {
 /** Describe the bridge in the status message. */
 function bridgeDescription(bridge: BridgeKey): string {
 	return bridge === "webSearch"
-		? "web-search bridge (official NaN MCP → mcp__nan-search__web_search)"
-		: "nan-mcp-server bridge (community media MCP → mcp__nan-media__generate_image/edit_image/text_to_speech/list_voices/speech_to_text)";
+		? "web-search bridge (official NaN MCP → mcp__nan_search__web_search)"
+		: "nan-mcp-server bridge (community media MCP → mcp__nan_media__generate_image/edit_image/text_to_speech/list_voices/speech_to_text)";
 }
 
 /** Check if a native server of this name is currently registered. */