@gtrabanco/pi-nan-provider 0.10.3 → 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.
 
@@ -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,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 | ✅ |
@@ -295,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.3",
+	"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/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-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:56:14.717Z",
+	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: [

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

package/src/context-overflow-classifier.ts

@@ -23,22 +23,50 @@
  *
  * This module makes the package **re-check the request size on the way out**
  * (one of the two upstream fixes the tracking issue names). After the request is
- * sent and the gateway answers, if
- *   - the terminal assistant message is an error whose text carries NaN's
- *     generic 400 marker, AND
- *   - the request we sent was estimated to exceed the model's context window,
- * then the error message is rewritten into a form that matches pi-ai's
- * documented overflow patterns, so pi compacts and retries instead of wedging.
- * The original provider text is preserved in the rewritten message. The
- * reclassification is deliberately conservative: a generic 400 on a
- * within-window request is left untouched, so unrelated 400s are never
+ * sent and the gateway answers, two independent branches reclassify:
+ *
+ * 1. **HTTP 400 branch** — keys on the **model's context window**. When the
+ *    terminal error carries NaN's generic 400 marker AND the estimated input
+ *    tokens exceed the destination model's `contextWindow`, the message is
+ *    rewritten. A 400 may be caused by other schema violations, so the rewrite
+ *    conservatively requires the request to be over the window.
+ *
+ * 2. **HTTP 524 branch** — keys on a **fixed cold-cache ceiling**
+ *    (`NAN_COLD_CACHE_CEILING_TOKENS`, 200,000). Cloudflare's 524
+ *    origin_response_timeout fires when a large cold prompt hangs past the 120s
+ *    proxy read timeout. A 524 on an over-ceiling request is an overflow
+ *    masquerading as a timeout; a 524 under the ceiling is a genuine transient
+ *    timeout. The ceiling is a *practical endpoint limit* (Cloudflare 120s vs
+ *    cold-prompt prefill), NOT a model capability — so the model's
+ *    `contextWindow` is irrelevant to the 524 reclassify decision. The rewritten
+ *    message still mentions the model window for user clarity, but the
+ *    overflow-classification hinges only on the ceiling.
+ *
+ * The original provider text is preserved in rewritten messages. The
+ * reclassification is deliberately conservative so unrelated errors are never
  * mislabelled as overflow.
  *
+ * ---
+ *
+ * Cold-cache 524 (issue #18): large COLD prompts (≳1 MB body / ~220k tokens) to
+ * https://api.nan.builders/v1/chat/completions hang past Cloudflare's 120s Proxy
+ * Read Timeout → HTTP 524 origin_response_timeout with JSON body
+ *   {"status":524,"error_name":"origin_response_timeout","retryable":true,...}
+ * (sometimes a Cloudflare HTML page for even larger bodies). Measured: cold
+ * 208,036 tokens (960 KB) succeeds (TTFT 12.9 s); ~220k and ~286k tokens cold
+ * → 524 at ~126 s. pi-ai classifies 524 as RETRYABLE (retrying an identical cold
+ * payload always fails) and its `isContextOverflow()` matches nothing, so the
+ * session wedges. When the error is a 524 AND the estimated input tokens exceed
+ * `NAN_COLD_CACHE_CEILING_TOKENS`, the error is rewritten into a pi-recognizable
+ * overflow message so pi compacts and retries instead of wedging. The original
+ * provider text is preserved. A 524 on a small request (under the ceiling) is
+ * left untouched — it is a genuine transient timeout.
+ *
  * Estimation ratio: the same chars/3.47 the issue's offline session measurements
  * use (`chars/3.47 + ~31K tools + ~12K system`). The system prompt and tool
  * schemas are counted explicitly, so the constant is only applied to the
  * message/character budget. This is a heuristic for deciding whether a generic
- * 400 is plausibly an overflow — it never fabricates model metadata.
+ * 400 / 524 is plausibly an overflow — it never fabricates model metadata.
  */
 
 import type {
@@ -52,6 +80,19 @@ import type {
 /** The exact generic body NaN's gateway returns for an over-window request. */
 export const NAN_GENERIC_BAD_REQUEST = "Invalid request. Check your request parameters.";
 
+/**
+ * Cloudflare 524 origin_response_timeout cold-cache ceiling (tokens).
+ *
+ * Measured (issue #18 repro): cold 208,036 tokens (960 KB) succeeds
+ * (TTFT 12.9 s); ~220k and ~286k tokens cold → 524 at ~126 s. 200,000 is a
+ * conservative midpoint — well below the working 208k measurement — so the
+ * working cold cache path is not affected while larger cold requests hit this
+ * rewrite. This is a practical endpoint ceiling (Cloudflare 120s proxy read
+ * timeout vs cold prompt prefill), NOT a model capability — contextWindow in
+ * the catalog must NOT change.
+ */
+export const NAN_COLD_CACHE_CEILING_TOKENS = 200_000;
+
 /**
  * Characters per token used for the request-size estimate. Same ratio as the
  * issue's offline measurements (chars/3.47); a conservative, provider-agnostic
@@ -93,11 +134,34 @@ export function isGenericNanBadRequest(message: Pick<AssistantMessage, "errorMes
 	return typeof message?.errorMessage === "string" && message.errorMessage.includes(NAN_GENERIC_BAD_REQUEST);
 }
 
+/**
+ * True when a terminal error message carries a Cloudflare 524
+ * origin_response_timeout marker. Matches the 524 status followed by either
+ * `origin_response_timeout` in the JSON body, or Cloudflare HTML markers
+ * (`Error 524` / `A timeout occurred`). Conservative: only these known
+ * markers are matched, not any arbitrary 524 response.
+ */
+function isCloudflare524(message: Pick<AssistantMessage, "errorMessage"> | undefined): boolean {
+	const text = message?.errorMessage;
+	if (typeof text !== "string") return false;
+	// Match the status code + origin_response_timeout JSON body.
+	if (text.includes("524") && text.includes("origin_response_timeout")) return true;
+	// Cloudflare HTML error page variant (occurs for very large bodies).
+	if (text.includes("524") && (text.includes("Error 524") || text.includes("A timeout occurred"))) return true;
+	return false;
+}
+
 /**
  * Reclassify a terminal assistant error as a context overflow when — and only
  * when — NaN returned its generic 400 for a request estimated to exceed the
- * model's context window. Mutates and returns the message (the same object
- * flows through the error event and `result()`).
+ * model's context window, OR when a Cloudflare 524 fires for an over-ceiling
+ * cold request. Mutates and returns the message (the same object flows through
+ * the error event and `result()`).
+ *
+ * The two error paths use independent thresholds:
+ * - 400: estimated > contextWindow  (conservative; a 400 may be schema-related)
+ * - 524: estimated > CEILING        (a 524 is either overflow or transient;
+ *                                    the ceiling is the discriminator)
  */
 export function classifyContextOverflowError<T extends AssistantMessage>(
 	message: T,
@@ -105,16 +169,43 @@ export function classifyContextOverflowError<T extends AssistantMessage>(
 	estimatedInputTokens: number,
 ): T {
 	if (message.stopReason !== "error") return message;
-	if (!isGenericNanBadRequest(message)) return message;
-	const contextWindow = model?.contextWindow ?? 0;
-	if (!Number.isFinite(contextWindow) || contextWindow <= 0) return message;
-	if (!Number.isFinite(estimatedInputTokens) || estimatedInputTokens <= contextWindow) return message;
-
-	message.errorMessage =
-		`Requested token count exceeds the model's maximum context length of ${contextWindow} tokens ` +
-		`(estimated ${Math.ceil(estimatedInputTokens)} input tokens). ` +
-		`NaN's gateway answered HTTP 400 "${NAN_GENERIC_BAD_REQUEST}" instead of naming the overflow, ` +
-		`so the context must be compacted before retrying.`;
+
+	const contextWindow = model?.contextWindow;
+	const hasValidWindow = Number.isFinite(contextWindow) && contextWindow! > 0;
+
+	// --- 400 branch: keys on the model's context window ---
+	if (isGenericNanBadRequest(message) && hasValidWindow
+		&& Number.isFinite(estimatedInputTokens)
+		&& estimatedInputTokens > contextWindow!) {
+		message.errorMessage =
+			`Requested token count exceeds the model's maximum context length of ${contextWindow!} tokens ` +
+			`(estimated ${Math.ceil(estimatedInputTokens)} input tokens). ` +
+			`NaN's gateway answered HTTP 400 "${NAN_GENERIC_BAD_REQUEST}" instead of naming the overflow, ` +
+			`so the context must be compacted before retrying.`;
+		return message;
+	}
+
+	// --- 524 branch: keys on the cold-cache ceiling only ---
+	// A 524 origin_response_timeout on an over-ceiling request means the edge
+	// timed out while prefilling a large cold prompt — it is an overflow, not a
+	// transient error. Small-requests that hit 524 are genuine timeouts.
+	if (isCloudflare524(message)
+		&& Number.isFinite(estimatedInputTokens)
+		&& estimatedInputTokens > NAN_COLD_CACHE_CEILING_TOKENS) {
+		const windowClause = hasValidWindow
+			? ` (declared model window: ${contextWindow!} tokens)`
+			: "";
+		message.errorMessage =
+			`Requested token count exceeds the maximum context length of ${NAN_COLD_CACHE_CEILING_TOKENS} tokens ` +
+			`servable with a cold prompt cache through NaN's endpoint` +
+			windowClause +
+			`, so the context must be compacted before retrying. ` +
+			`(estimated ${Math.ceil(estimatedInputTokens)} input tokens; ` +
+			`Cloudflare answers HTTP 524 origin_response_timeout past the 120s proxy read timeout). ` +
+			`Original error: ${message.errorMessage}.`;
+		return message;
+	}
+
 	return message;
 }
 
@@ -178,4 +269,4 @@ export function withContextOverflowClassification(api: ProviderStreams): Provide
 		streamSimple: (model, context, options) =>
 			classifyStreamContextOverflow(api.streamSimple(model, context, options), model, estimateRequestTokens(context)),
 	};
-}
+}