@gtrabanco/pi-nan-provider 0.10.2 → 1.0.0

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.
 
@@ -198,9 +200,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`
@@ -240,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.
@@ -275,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). 
 
@@ -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)
@@ -99,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 |
@@ -130,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
@@ -143,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.*
@@ -158,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
 
@@ -287,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 | ✅ |
@@ -296,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). 
 
@@ -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)
@@ -99,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 |
@@ -129,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
@@ -140,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.*
@@ -155,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
 
@@ -284,6 +321,8 @@ 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 | ✅ |
@@ -293,6 +332,17 @@ Baseline catalog (verified against [NaN docs](https://nan.builders/docs/models)
 | `glm5.3-flash` | 1,000,000 | 131,072 | text, image | ✅ |
 | `qwen3.8-flash` | 262,144 | 131,072 | text, image | ✅ |
 
+> [!NOTE]
+> **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.2",
+	"version": "1.0.0",
 	"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/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
@@ -346,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/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:18:48.654Z
+// Source: https://models.dev/api.json (provider "nan"), fetched 2026-10-02T00:02:21.641Z
 // 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.
@@ -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:18:48.654Z",
+	fetchedAt: "2026-10-02T00:02:21.641Z",
 	modelCount: 6,
 	models: ["deepseek-v4-flash","gemma4","glm5.3-flash","mimo-v2.6-flash","qwen3.6","qwen3.8-flash"],
 	notes: [
@@ -463,6 +463,11 @@ 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=[\"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.",

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. */