@gtrabanco/pi-nan-provider 0.5.1 → 0.6.1

package/AGENTS.md

@@ -89,9 +89,21 @@ Every PR that changes code MUST bump `package.json` version in the same PR; CI p
 - Capability values that diverge from models.dev are recorded as build-time
   `MANUAL_OVERRIDES` (mandatory provenance note) in `scripts/manual-overrides.ts`,
   applied by `scripts/generate-models.ts` — never hand-edited into
-  `scripts/models.generated.ts` and never invented. e.g. qwen3.8-flash
-  contextWindow 1,000,000 (maintainer-confirmed 2026-09-05; models.dev and NaN
-  docs still listed 262,144 that day).
+  `scripts/models.generated.ts` and never invented. e.g. deepseek-v4-flash
+  image input (Vision-Exp variant; models.dev lists text only). Re-verify
+  overrides when the sources update: the qwen3.8-flash contextWindow 1,000,000
+  override (maintainer-confirmed 2026-09-05) was withdrawn 2026-09-07 — the
+  updated NaN docs still say 262K "the model's native window" and models.dev
+  agrees at 262,144.
+- NaN's official chat model list (https://nan.builders/openapi.json `model`
+  param description + https://nan.builders/docs/models, checked 2026-09-07):
+  community `deepseek-v4-flash`, `mimo-v2.5`, `qwen3.8-flash`, `glm5.3-flash`,
+  `qwen3.6`, `gemma4` (all text+image vision) + premium-tier `glm5.3`
+  (~753B MoE, text-only input, 1M context, 400M tokens/rolling 4h window).
+  `glm5.2` was removed by the provider (2026-09-05); models.dev may still list
+  it — the generator excludes it via `PROVIDER_REMOVED_MODEL_IDS`. Non-chat
+  endpoints: qwen3-embedding, rerank, kokoro (TTS), whisper (STT),
+  flux-2-klein (images) — MCP-bridge territory, not chat catalog models.
 - Relative imports inside this package use `.ts` extensions (pi's official
   extension examples do the same; pi transpiles extension sources).
 - pi intentionally has NO built-in MCP client (docs/usage.md). MCP integration
@@ -103,7 +115,10 @@ Every PR that changes code MUST bump `package.json` version in the same PR; CI p
     "growing registry" — use tools/list to discover.
   - Community `nan-mcp-server` (https://github.com/luciferfran/nan-mcp-server):
     stdio MCP server, spawned per tool call (lazy), opt-in NAN_MEDIA_MCP=1,
-    version-pinned via NAN_MEDIA_MCP_VERSION (default 1.0.7) or a full command
+    version-pinned via NAN_MEDIA_MCP_VERSION (default 1.0.8) or a full command
     override via NAN_MEDIA_MCP_COMMAND. Tools: generate_image, edit_image,
     text_to_speech, list_voices, speech_to_text, embed, rerank, list_models
-    (we bridge the audio/image/transcription scope).
+    (we bridge the audio/image/transcription scope). An automated check
+    (scripts/check-nan-mcp-server.ts + .github/workflows/check-nan-mcp-server-update.yml)
+    compares the npm registry against the pin weekly and files a `dependencies` issue
+    with a breaking/safe verdict from the live server tool surface (unpkg).

package/README.es.md

@@ -98,14 +98,33 @@ Variables de entorno:
 | Variable | Por defecto | Significado |
 |---|---|---|
 | `NAN_MEDIA_MCP` | — | Override por sesión del puente de media: cualquier valor explícito (incl. `0`) gana al toggle persistido de `/nan-mcp`; sin definir → persistido/por defecto |
-| `NAN_MEDIA_MCP_VERSION` | `1.0.7` | Versión del servidor fijada para `npx -y nan-mcp-server@<v>` (recomendación de supply-chain del propio proyecto) |
-| `NAN_MEDIA_MCP_COMMAND` | — | Comando personalizado completo, p. ej. `bunx nan-mcp-server@1.0.7` |
+| `NAN_MEDIA_MCP_VERSION` | `1.0.8` | Versión del servidor fijada para `npx -y nan-mcp-server@<v>` (recomendación de supply-chain del propio proyecto) |
+| `NAN_MEDIA_MCP_COMMAND` | — | Comando personalizado completo, p. ej. `bunx nan-mcp-server@1.0.8` |
+
+#### Detección automatizada de actualizaciones
+
+Una nueva versión de `nan-mcp-server` no desviará silenciosamente el pin de esta conexión. El
+planificador (`.github/workflows/check-nan-mcp-server-update.yml`) ejecuta `bun run scripts/check-nan-mcp-server.ts`
+semanalmente y, cuando el registro npm muestra una versión más reciente, abre (o refresca) un único
+issue etiquetado `dependencies` que describe si el bump es **breaking** o **seguro**, más la lista de
+commits aguas arriba. Puedes ejecutarlo localmente en cualquier momento:
+
+```bash
+bun run check-nan-mcp-server            # informe legible
+bun run check-nan-mcp-server --json     # JSON para máquina
+bun run check-nan-mcp-server --issue    # crea/refresca el issue (requiere GITHUB_TOKEN)
+```
+
+La decisión se toma a partir de la *superficie de tools* en vivo (vía unpkg), no de docs obsoletos: si
+el último servidor sigue exponiendo todas las tools conectadas (`generate_image`, `edit_image`,
+`text_to_speech`, `list_voices`, `speech_to_text`), el bump se reporta como **no rompente**; si elimina
+o renombra alguna tool conectada, el issue se marca **breaking** para revisión manual antes de subir.
 | `NAN_MEDIA_MCP_TIMEOUT_MS` | `120000` | Timeout por llamada; el proceso se mata al expirar |
 | `NAN_MCP_TOOLS` | — | Override por sesión del puente oficial: `0`/`false`/`off` desactiva `nan_web_search`; sin definir → persistido/por defecto |
 
 ## Modelos
 
-Catálogo base (de models.dev, proveedor `nan`, obtenido 2026-09-04 — límites *servidos* por NaN, no máximos teóricos):
+Catálogo base (de models.dev, proveedor `nan`, obtenido 2026-09-07 y corregido contra [los docs de NaN](https://nan.builders/docs/models) y [openapi.json](https://nan.builders/openapi.json) — límites *servidos* por NaN, no máximos teóricos):
 
 | Modelo | Contexto | Máx. salida | Entrada | Razonamiento |
 |---|---|---|---|---|
@@ -113,19 +132,18 @@ Catálogo base (de models.dev, proveedor `nan`, obtenido 2026-09-04 — límites
 | `gemma4` | 262,144 | 32,768 | texto, imagen | sí |
 | `deepseek-v4-flash` | 1,000,000 | 384,000 | texto, imagen | sí |
 | `mimo-v2.5` | 1,048,576 | 131,072 | texto, imagen | sí |
-| `glm5.2` | 500,000 | 131,072 | texto | sí |
 | `glm5.3-flash` | 1,000,000 | 131,072 | texto, imagen | sí |
-| `qwen3.8-flash` | 1,000,000 | 131,072 | texto, imagen | sí |
+| `qwen3.8-flash` | 262,144 | 131,072 | texto, imagen | sí |
 
 Notas (grabadas por entrada en `scripts/models.generated.ts`):
 
-- La ventana de contexto de `qwen3.8-flash` está confirmada por el mantenedor en 1M (2026-09-05); models.dev y los docs de NaN aún listaban 262,144 en esa fecha. Este tipo de divergencias se registran como `MANUAL_OVERRIDES` en tiempo de build (con procedencia) en `scripts/manual-overrides.ts` — añade una ahí en vez de editar el fichero generado.
-
-- `deepseek-v4-flash` incluye entrada de imagen porque NaN sirve la variante Vision-Exp ([docs de NaN](https://nan.builders/docs/models)); models.dev la lista como solo texto.
+- `qwen3.8-flash` sirve 262K tokens, «la ventana nativa del modelo» ([docs de NaN](https://nan.builders/docs/models), 2026-09-07). Un override previo de 1M (confirmado por el mantenedor el 2026-09-05) se retiró cuando los docs actualizados siguieron diciendo 262K; models.dev coincide en 262,144. Este tipo de divergencias se registran como `MANUAL_OVERRIDES` en tiempo de build (con procedencia) en `scripts/manual-overrides.ts` — añade una ahí en vez de editar el fichero generado.
+- `deepseek-v4-flash` incluye entrada de imagen porque NaN sirve la variante Vision-Exp ([docs de NaN](https://nan.builders/docs/models), confirmado por los content-parts de visión en [openapi.json](https://nan.builders/openapi.json)); models.dev la lista como solo texto.
+- `glm5.2` fue eliminado por NaN (2026-09-05). models.dev aún lo listaba el 2026-09-07, así que el generador lo excluye vía `PROVIDER_REMOVED_MODEL_IDS` con la razón registrada — una regeneración no debe resucitar modelos retirados por el proveedor.
 - `mimo-v2.5` es omnimodal (texto/imagen/audio) en NaN, pero el tipo de modelo de pi solo representa entrada texto/imagen, así que el audio se omite en `input`.
 - NaN factura por cuota de membresía, que models.dev reporta como coste cero por token — el coste mostrado por pi será $0.
 - Compat (`supportsDeveloperRole: false`, `supportsReasoningEffort: true`, `supportsUsageInStreaming: true`, `maxTokensField: "max_tokens"`) coincide con la config LiteLLM probada en batalla que este paquete reemplaza; el ejemplo de los docs de NaN (`supportsDeveloperRole: true`) no está probado.
-- **Tier/cuota**: qué modelos puedes llamar lo decide tu membresía de NaN. Con clave, el fetch en vivo refleja exactamente eso (ver *Cómo funciona* — detección de tier). El GLM 5.3 de tier premium no está en el proveedor `nan` de models.dev; solo está `glm5.3-flash`.
+- **Tier/cuota**: qué modelos puedes llamar lo decide tu membresía de NaN. Con clave, el fetch en vivo refleja exactamente eso (ver *Cómo funciona* — detección de tier). El `glm5.3` de tier premium no está en el proveedor `nan` de models.dev y ninguna fuente documenta su límite de salida, así que no entra en el catálogo estático (marcado como no emitible en los metadatos); las claves premium lo reciben en vivo vía el refresh de `/models`, con límites conservadores (128K contexto / 4K salida). Solo está `glm5.3-flash` en el catálogo estático.
 
 ### Relación con `~/.pi/agent/models.json`
 

package/README.md

@@ -98,14 +98,33 @@ Environment variables:
 | Variable | Default | Meaning |
 |---|---|---|
 | `NAN_MEDIA_MCP` | — | Per-session override for the media bridge: any explicit value (incl. `0`) beats the `/nan-mcp` persisted toggle; unset → persisted/default |
-| `NAN_MEDIA_MCP_VERSION` | `1.0.7` | Pinned server version for `npx -y nan-mcp-server@<v>` (upstream's own supply-chain recommendation) |
-| `NAN_MEDIA_MCP_COMMAND` | — | Full custom command, e.g. `bunx nan-mcp-server@1.0.7` |
+| `NAN_MEDIA_MCP_VERSION` | `1.0.8` | Pinned server version for `npx -y nan-mcp-server@<v>` (upstream's own supply-chain recommendation) |
+| `NAN_MEDIA_MCP_COMMAND` | — | Full custom command, e.g. `bunx nan-mcp-server@1.0.8` |
+
+#### Automated update detection
+
+A newer `nan-mcp-server` release won't silently drift this bridge's pin. The scheduler
+(`.github/workflows/check-nan-mcp-server-update.yml`) runs `bun run scripts/check-nan-mcp-server.ts`
+weekly and, when the npm registry shows a newer version, opens (or refreshes) one
+`dependencies`-labelled issue describing whether the bump is **breaking** or **safe**, plus the
+upstream commit list. Run it locally any time:
+
+```bash
+bun run check-nan-mcp-server            # human-readable report
+bun run check-nan-mcp-server --json     # machine-readable JSON
+bun run check-nan-mcp-server --issue    # create/refresh the issue (needs GITHUB_TOKEN)
+```
+
+The decision is made from the *live* server tool surface (via unpkg), not from stale docs: if the
+latest server still exposes every bridged tool (`generate_image`, `edit_image`, `text_to_speech`,
+`list_voices`, `speech_to_text`), the bump is reported as **non-breaking**; if it drops or renames a
+bridged tool, the issue is flagged **breaking** for manual review before bumping.
 | `NAN_MEDIA_MCP_TIMEOUT_MS` | `120000` | Per-call timeout; the process is killed after it |
 | `NAN_MCP_TOOLS` | — | Per-session override for the official bridge: `0`/`false`/`off` disables `nan_web_search`; unset → persisted/default |
 
 ## Models
 
-Baseline catalog (from models.dev, provider `nan`, fetched 2026-09-04 — NaN's *served* limits, not raw model maxima):
+Baseline catalog (from models.dev, provider `nan`, fetched 2026-09-07 and corrected against [NaN's docs](https://nan.builders/docs/models) and [openapi.json](https://nan.builders/openapi.json) — NaN's *served* limits, not raw model maxima):
 
 | Model | Context | Max output | Input | Reasoning |
 |---|---|---|---|---|
@@ -113,18 +132,18 @@ Baseline catalog (from models.dev, provider `nan`, fetched 2026-09-04 — NaN's
 | `gemma4` | 262,144 | 32,768 | text, image | yes |
 | `deepseek-v4-flash` | 1,000,000 | 384,000 | text, image | yes |
 | `mimo-v2.5` | 1,048,576 | 131,072 | text, image | yes |
-| `glm5.2` | 500,000 | 131,072 | text | yes |
 | `glm5.3-flash` | 1,000,000 | 131,072 | text, image | yes |
-| `qwen3.8-flash` | 1,000,000 | 131,072 | text, image | yes |
+| `qwen3.8-flash` | 262,144 | 131,072 | text, image | yes |
 
 Notes (recorded per entry in `scripts/models.generated.ts`):
 
-- `qwen3.8-flash` context window is maintainer-confirmed at 1M (2026-09-05); models.dev and NaN's docs still listed 262,144 at that date. Divergences like this are recorded as build-time `MANUAL_OVERRIDES` (with provenance) in `scripts/manual-overrides.ts` — apply one instead of editing the generated file.
-- `deepseek-v4-flash` includes image input because NaN serves the Vision-Exp variant ([NaN docs](https://nan.builders/docs/models)); models.dev lists text only.
+- `qwen3.8-flash` serves 262K tokens, "the model's native window" ([NaN docs](https://nan.builders/docs/models), 2026-09-07). An earlier 1M override (maintainer-confirmed 2026-09-05) was withdrawn once the updated docs still said 262K; models.dev agrees at 262,144. Divergences like this are recorded as build-time `MANUAL_OVERRIDES` (with provenance) in `scripts/manual-overrides.ts` — apply one instead of editing the generated file.
+- `deepseek-v4-flash` includes image input because NaN serves the Vision-Exp variant ([NaN docs](https://nan.builders/docs/models), confirmed by the vision content-parts in [openapi.json](https://nan.builders/openapi.json)); models.dev lists text only.
+- `glm5.2` was removed by NaN (2026-09-05). models.dev still listed it on 2026-09-07, so the generator excludes it via `PROVIDER_REMOVED_MODEL_IDS` with a recorded reason — a regeneration must not resurrect provider-removed models.
 - `mimo-v2.5` is omnimodal (text/image/audio) on NaN, but pi's model type only represents text/image input, so audio is dropped from `input`.
 - NaN bills via membership quota, which models.dev reports as zero per-token cost — pi's cost display will read $0.
 - Compat (`supportsDeveloperRole: false`, `supportsReasoningEffort: true`, `supportsUsageInStreaming: true`, `maxTokensField: "max_tokens"`) matches the battle-tested LiteLLM config this package replaces; NaN's docs example (`supportsDeveloperRole: true`) is not battle-tested.
-- **Tier/quota**: which models you can call is decided by your NaN membership. With a key, the live fetch reflects exactly that (see *How it works* — tier detection). The premium-tier GLM 5.3 is not in the models.dev `nan` provider at all; only `glm5.3-flash` is.
+- **Tier/quota**: which models you can call is decided by your NaN membership. With a key, the live fetch reflects exactly that (see *How it works* — tier detection). The premium-tier `glm5.3` is absent from the models.dev `nan` provider and no source documents its max output tokens, so it is not in the static catalog (flagged as unemittable in the catalog metadata); premium keys still get it live via the `/models` refresh with conservative placeholder limits (128K context / 4K output). Only `glm5.3-flash` is in the static catalog.
 
 ### Relationship to `~/.pi/agent/models.json`
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gtrabanco/pi-nan-provider",
-	"version": "0.5.1",
+	"version": "0.6.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",
@@ -35,6 +35,7 @@
 	],
 	"scripts": {
 		"generate-models": "bun run scripts/generate-models.ts",
+		"check-nan-mcp-server": "bun run scripts/check-nan-mcp-server.ts",
 		"prepublishOnly": "bun run generate-models && bun test && bun run typecheck",
 		"test": "bun test",
 		"typecheck": "bunx tsc --noEmit"

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

@@ -0,0 +1,426 @@
+#!/usr/bin/env bun
+/**
+ * Detect whether an updated `nan-mcp-server` is available and, if so, decide
+ * whether it is safe to bump the pinned version this package bridges.
+ *
+ * This is the automated companion to the manual "should we update?" question
+ * for the community stdio MCP server (`nan-mcp-server`, the media bridge). It
+ * exists because pi implements NO MCP client — we bridge the server's tools as
+ * native pi tools, and the bridge is pinned to a version via
+ * `DEFAULT_NAN_MEDIA_MCP_VERSION`. When the upstream server ships a new
+ * version we want a signal, not a silent drift.
+ *
+ * What it checks (all live, no human guesswork):
+ *   1. Latest published `nan-mcp-server` version on the npm registry.
+ *   2. Whether the latest version is newer than the pinned version.
+ *   3. The *tool surface* of the latest server vs the tools we bridge: if the
+ *      latest server still exposes every bridged tool, the update is **safe**
+ *      (non-breaking) even if the implementation changed. If it dropped or
+ *      renamed a bridged tool, the bump is **breaking** and needs manual
+ *      review before proceeding — an agent check cannot auto-bump that.
+ *   4. The upstream commit list between the pinned and latest versions, so a
+ *      maintainer sees WHAT changed without re-deriving from stale docs.
+ *
+ * Output: a single structured `NanMcpServerCheckReport` (JSON). The script
+ * exits 0 when up-to-date or when the check cannot be completed (so a cron is
+ * quiet unless there is news), and it creates/updates a GitHub issue when an
+ * update is available and `GITHUB_TOKEN` is present.
+ *
+ * Usage:
+ *   bun run scripts/check-nan-mcp-server.ts            # report to stdout
+ *   bun run scripts/check-nan-mcp-server.ts --json     # machine-readable JSON
+ *   bun run scripts/check-nan-mcp-server.ts --issue    # create/update an issue (needs GITHUB_TOKEN)
+ *
+ * The pure decision logic (`parseVersion`, `compareVersions`, `extractServerTools`,
+ * `assessUpdate`, `buildReport`) is exported for unit tests so the whole verdict
+ * is verifiable without touching the network. The network fetchers accept an
+ * injected `fetch` so tests can stub the registry/unpkg/github sources.
+ *
+ * Exit codes: 0 always (a cron should be quiet unless a human acts). Use
+ * `--json` to consume the report and decide what to do with it.
+ */
+
+import {
+	DEFAULT_NAN_MEDIA_MCP_VERSION,
+	NAN_MEDIA_MCP_SERVER_TOOLS,
+} from "../src/mcp/nan-media.ts";
+
+/** npm package name of the community stdio MCP server we bridge. */
+export const NAN_MCP_SERVER_PACKAGE = "nan-mcp-server";
+/** npm registry endpoint for the package's latest release. */
+export const NAN_MCP_SERVER_REGISTRY_URL = "https://registry.npmjs.org/nan-mcp-server/latest";
+/** unpkg CDN path to the published server source, used to extract the tool surface. */
+export const NAN_MCP_SERVER_SOURCE_URL = (version: string) =>
+	`https://unpkg.com/nan-mcp-server@${version}/server.js`;
+/** GitHub compare API for the upstream commit list between two tags. */
+export const NAN_MCP_SERVER_COMPARE_URL = (from: string, to: string) =>
+	`https://api.github.com/repos/luciferfran/nan-mcp-server/compare/v${from.replace(/^v/, "")}...v${to.replace(/^v/, "")}`;
+
+/** GitHub search-issues endpoint used to dedupe the update issue. */
+const GITHUB_SEARCH_ISSUES_URL =
+	"https://api.github.com/search/issues?q=" +
+	"repo:gtrabanco/pi-nan-provider+is:issue+is:open+in:title" +
+	'+label:dependencies+type:issue+"nan-mcp-server update"';
+
+/** Label to attach to the auto-created update issue (dedupe key + visibility). */
+export const NAN_MCP_UPDATE_ISSUE_LABEL = "dependencies";
+/** Title template; the version pair is appended so each update is its own issue. */
+export const NAN_MCP_UPDATE_ISSUE_TITLE_PREFIX = "[auto] nan-mcp-server update available";
+
+export interface NanMcpServerCheckReport {
+	/** npm package scanned. */
+	package: string;
+	/** Version pinned in this package's bridge (source of truth: nan-media.ts). */
+	pinnedVersion: string;
+	/** Latest version published on npm; null when the registry could not be read. */
+	latestVersion: string | null;
+	/** true when latestVersion is strictly newer than pinnedVersion. */
+	updateAvailable: boolean;
+	/** How the verdict was reached: registry in reach, no drift, or an error. */
+	status: "up-to-date" | "update-available" | "check-failed";
+	/** true when a bridged tool is missing from the latest server surface. */
+	breaking: boolean;
+	/** Tools added by the latest server that we do NOT bridge (informational). */
+	addedTools: string[];
+	/** Bridged tools dropped/renamed by the latest server (breaking → manual). */
+	removedTools: string[];
+	/** Upstream commit subjects between pinned and latest (when reachable). */
+	changelog: string[];
+	/** Human-readable verdict sentence. */
+	reason: string;
+	/** When the check could not reach a source (registry/unpkg/github). */
+	error?: string;
+}
+
+/**
+ * Parse a semver-ish string (`1.0.8`, `v1.0.8`) into numeric major/minor/patch.
+ * Non-numeric release segments are clamped to 0 so `1.0.8` and `1.0.8-rc.1`
+ * compare sensibly; malformed input yields `[0, 0, 0]` (never throws).
+ */
+export function parseVersion(input: string): [number, number, number] {
+	const cleaned = String(input).trim().replace(/^v/, "").split(/[-+.]/);
+	const toNum = (segment: string | undefined) => {
+		const n = Number.parseInt(segment ?? "", 10);
+		return Number.isFinite(n) ? n : 0;
+	};
+	return [toNum(cleaned[0]), toNum(cleaned[1]), toNum(cleaned[2])];
+}
+
+/**
+ * Compare two version strings. Returns 1 when `a` is newer, -1 when older,
+ * 0 when equal. Comparable to a numeric semver compare for x.y.z inputs.
+ */
+export function compareVersions(a: string, b: string): number {
+	const [amaj, amin, apatch] = parseVersion(a);
+	const [bmaj, bmin, bpatch] = parseVersion(b);
+	if (amaj !== bmaj) return amaj > bmaj ? 1 : -1;
+	if (amin !== bmin) return amin > bmin ? 1 : -1;
+	if (apatch !== bpatch) return apatch > bpatch ? 1 : -1;
+	return 0;
+}
+
+/** Extract every `registerTool("NAME")` from a server.js source string. */
+export function extractServerTools(source: string): string[] {
+	const names = new Set<string>();
+	const re = /registerTool\(\s*["']([^"']+)["']/g;
+	let match: RegExpExecArray | null;
+	while ((match = re.exec(source)) !== null) {
+		names.add(match[1]!);
+	}
+	return [...names].sort();
+}
+
+/**
+ * Compare the latest server tool surface against the bridged tools and decide
+ * whether the update is safe to bump. The only hard break is a bridged tool
+ * disappearing (dropped or renamed); anything else — new tools, bug fixes,
+ * schema tightening (e.g. `edit_image` now rejects >4 images) — is safe for
+ * our bridge, because we forward the params the schema already documents.
+ */
+export function assessUpdate(latestTools: string[]): {
+	breaking: boolean;
+	addedTools: string[];
+	removedTools: string[];
+	reason: string;
+} {
+	const bridged: readonly string[] = [...NAN_MEDIA_MCP_SERVER_TOOLS];
+	const latest = new Set(latestTools.map((t) => t.trim()));
+
+	const removedTools = bridged.filter((tool) => !latest.has(tool));
+	const addedTools = latestTools.filter((tool) => !bridged.includes(tool));
+
+	const breaking = removedTools.length > 0;
+
+	let reason: string;
+	if (breaking) {
+		reason =
+			`BREAKING: the latest nan-mcp-server no longer exposes ${removedTools.join(", ")}. ` +
+			"Bumping the pin would break the bridged tool(s) — manual review required before deciding.";
+	} else if (addedTools.length > 0) {
+		reason = `Safe to bump (non-breaking): every bridged tool is still present. New upstream tool(s) ${addedTools.join(", ")} are NOT bridged by this package (optional future work).`;
+	} else {
+		reason = "Safe to bump (non-breaking): every bridged tool is still present, and no new upstream tools were added.";
+	}
+
+	return { breaking, addedTools, removedTools, reason };
+}
+
+/**
+ * Build the full report from already-fetched data. Pure — no network. Missing
+ * or stale inputs degrade to `check-failed`, and an update is only reported
+ * when the latest version is strictly newer than the pinned one.
+ */
+export function buildReport(input: {
+	pinnedVersion: string;
+	latestVersion: string | null;
+	latestTools: string[];
+	changelog: string[];
+	error?: string;
+}): NanMcpServerCheckReport {
+	const { pinnedVersion, latestVersion, latestTools, changelog, error } = input;
+
+	if (error) {
+		return {
+			package: NAN_MCP_SERVER_PACKAGE,
+			pinnedVersion,
+			latestVersion: null,
+			updateAvailable: false,
+			status: "check-failed",
+			breaking: false,
+			addedTools: [],
+			removedTools: [],
+			changelog: [],
+			reason: `Could not complete the check: ${error}`,
+			error,
+		};
+	}
+
+	if (latestVersion === null) {
+		return {
+			package: NAN_MCP_SERVER_PACKAGE,
+			pinnedVersion,
+			latestVersion: null,
+			updateAvailable: false,
+			status: "check-failed",
+			breaking: false,
+			addedTools: [],
+			removedTools: [],
+			changelog: [],
+			reason: "Could not read the npm registry for the latest version.",
+			error: "registry-unreachable",
+		};
+	}
+
+	const updateAvailable = compareVersions(latestVersion, pinnedVersion) > 0;
+	if (!updateAvailable) {
+		return {
+			package: NAN_MCP_SERVER_PACKAGE,
+			pinnedVersion,
+			latestVersion,
+			updateAvailable: false,
+			status: "up-to-date",
+			breaking: false,
+			addedTools: [],
+			removedTools: [],
+			changelog: [],
+			reason: `Up to date: pinned ${pinnedVersion} is not older than latest ${latestVersion}.`,
+		};
+	}
+
+	const verdict = assessUpdate(latestTools);
+	return {
+		package: NAN_MCP_SERVER_PACKAGE,
+		pinnedVersion,
+		latestVersion,
+		updateAvailable: true,
+		status: "update-available",
+		breaking: verdict.breaking,
+		addedTools: verdict.addedTools,
+		removedTools: verdict.removedTools,
+		changelog,
+		reason: verdict.reason,
+	};
+}
+
+/** A minimal fetch-compatible signature so tests can stub it without undici types. */
+export type FetchLike = (url: string, init?: { headers?: Record<string, string> }) => Promise<Response>;
+
+async function readJson<T>(url: string, fetchImpl: FetchLike, headers?: Record<string, string>): Promise<T> {
+	const res = await fetchImpl(url, { headers });
+	if (!res.ok) {
+		throw new Error(`HTTP ${res.status} from ${url}`);
+	}
+	return (await res.json()) as T;
+}
+
+/** Fetch the latest published version of the package from the npm registry. */
+export async function fetchLatestVersion(fetchImpl: FetchLike = fetch): Promise<string> {
+	const data = await readJson<{ version?: string; "dist-tags"?: { latest?: string } }>(
+		NAN_MCP_SERVER_REGISTRY_URL,
+		fetchImpl,
+	);
+	const version = data["dist-tags"]?.latest ?? data.version;
+	if (!version) throw new Error("npm registry response had no version");
+	return version;
+}
+
+/** Fetch the published server.js source and extract its tool surface. */
+export async function fetchServerTools(
+	version: string,
+	fetchImpl: FetchLike = fetch,
+): Promise<string[]> {
+	const res = await fetchImpl(NAN_MCP_SERVER_SOURCE_URL(version));
+	if (!res.ok) throw new Error(`HTTP ${res.status} from ${NAN_MCP_SERVER_SOURCE_URL(version)}`);
+	return extractServerTools(await res.text());
+}
+
+/** Fetch upstream commit subjects between two tags (best-effort; empty on failure). */
+export async function fetchChangelog(
+	from: string,
+	to: string,
+	fetchImpl: FetchLike = fetch,
+): Promise<string[]> {
+	try {
+		const data = await readJson<{ commits?: Array<{ commit?: { message?: string } }> }>(
+			NAN_MCP_SERVER_COMPARE_URL(from, to),
+			fetchImpl,
+		);
+		return (data.commits ?? [])
+			.map((c) => c.commit?.message?.split("\n")[0]?.trim() ?? "")
+			.filter(Boolean);
+	} catch {
+		return [];
+	}
+}
+
+const ARGS = process.argv.slice(2);
+/** Rendered issue body from a report — what a maintainer reads to decide. */
+export function renderIssueBody(report: NanMcpServerCheckReport): string {
+	const lines: string[] = [];
+	lines.push(`**Package**: \`${report.package}\``);
+	lines.push(`**Pinned by this package**: \`${report.pinnedVersion}\``);
+	lines.push(`**Latest on npm**: \`${report.latestVersion ?? "unknown"}\``);
+	lines.push(`**Verdict**: ${report.breaking ? "⚠️ BREAKING — manual review required" : "✅ Safe to bump (non-breaking)"}`);
+	lines.push("");
+	lines.push(`> ${report.reason}`);
+	lines.push("");
+	if (report.changelog.length > 0) {
+		lines.push("### Upstream changes");
+		lines.push("", ...report.changelog.map((c) => `- ${c}`), "");
+	}
+	lines.push("### To bump");
+	lines.push(
+		`1. Edit \`DEFAULT_NAN_MEDIA_MCP_VERSION\` in \`src/mcp/nan-media.ts\` from \`${report.pinnedVersion}\` to \`${report.latestVersion}\`.`,
+	);
+	lines.push("2. Run \`bun test && bun run typecheck\`.");
+	lines.push(
+		report.breaking
+			? "3. Investigate the removed tool(s) — decide whether to bridge an alternative or keep the older pin."
+			: "3. Commit the bump and close this issue (it was auto-created).",
+	);
+	return lines.join("\n");
+}
+
+/** GitHub API root for this repository's issues. */
+export const NAN_MCP_REPO_ISSUES_URL = "https://api.github.com/repos/gtrabanco/pi-nan-provider/issues";
+
+async function sendIssueRequest<T>(
+	url: string,
+	method: string,
+	body: object | undefined,
+	token: string,
+): Promise<T> {
+	const res = await fetch(url, {
+		method,
+		headers: {
+			Authorization: `Bearer ${token}`,
+			Accept: "application/vnd.github+json",
+			...(body ? { "Content-Type": "application/json" } : {}),
+		},
+		...(body ? { body: JSON.stringify(body) } : {}),
+	});
+	if (!res.ok) throw new Error(`GitHub API ${method} ${url} → HTTP ${res.status}`);
+	return (await res.json()) as T;
+}
+
+/**
+ * Create a pre-engineered update issue, or refresh an existing open one with
+ * the same title+label instead of stacking duplicates across cron runs.
+ * Returns the issue URL (web or API) so the caller can surface it.
+ */
+export async function createOrUpdateIssue(
+	report: NanMcpServerCheckReport,
+	token: string,
+): Promise<string> {
+	const title = `${NAN_MCP_UPDATE_ISSUE_TITLE_PREFIX}: ${report.pinnedVersion} → ${report.latestVersion ?? "?"}`;
+	const body = renderIssueBody(report);
+
+	// Dedupe key: an OPEN issue whose title matches AND carries the label.
+	const searchUrl = `${GITHUB_SEARCH_ISSUES_URL}+${encodeURIComponent(`"${title}"`)}`;
+	const search = await sendIssueRequest<{ items?: Array<{ number: number; html_url: string }> }>(
+		searchUrl,
+		"GET",
+		undefined,
+		token,
+	);
+	const existing = search.items?.[0];
+	if (existing) {
+		const patchUrl = `${NAN_MCP_REPO_ISSUES_URL}/${existing.number}`;
+		await sendIssueRequest(patchUrl, "PATCH", { body }, token);
+		return existing.html_url;
+	}
+
+	const created = await sendIssueRequest<{ html_url: string }>(
+		NAN_MCP_REPO_ISSUES_URL,
+		"POST",
+		{ title, body, labels: [NAN_MCP_UPDATE_ISSUE_LABEL] },
+		token,
+	);
+	return created.html_url;
+}
+
+/** Main entry point. */
+async function main(): Promise<void> {
+	let report: NanMcpServerCheckReport;
+	try {
+		const pinnedVersion = DEFAULT_NAN_MEDIA_MCP_VERSION;
+		const latestVersion = await fetchLatestVersion();
+		let latestTools: string[] = [];
+		let changelog: string[] = [];
+		if (compareVersions(latestVersion, pinnedVersion) > 0) {
+			latestTools = await fetchServerTools(latestVersion).catch(() => []);
+			changelog = await fetchChangelog(pinnedVersion, latestVersion);
+		}
+		report = buildReport({ pinnedVersion, latestVersion, latestTools, changelog });
+	} catch (error) {
+		report = buildReport({
+			pinnedVersion: DEFAULT_NAN_MEDIA_MCP_VERSION,
+			latestVersion: null,
+			latestTools: [],
+			changelog: [],
+			error: error instanceof Error ? error.message : String(error),
+		});
+	}
+
+	if (ARGS.includes("--json")) {
+		console.log(JSON.stringify(report, null, 2));
+	} else {
+		console.log(`nan-mcp-server: pinned ${report.pinnedVersion}, latest ${report.latestVersion ?? "unknown"}`);
+		console.log(`  status: ${report.status}  breaking: ${report.breaking}`);
+		console.log(`  ${report.reason}`);
+		if (report.changelog.length > 0) {
+			console.log("  upstream:");
+			for (const c of report.changelog) console.log(`    - ${c}`);
+		}
+	}
+
+	const token = process.env.GITHUB_TOKEN;
+	if (ARGS.includes("--issue") && report.status === "update-available" && token) {
+		const url = await createOrUpdateIssue(report, token);
+		console.log(`  issue: ${url}`);
+	} else if (ARGS.includes("--issue") && report.status === "update-available" && !token) {
+		console.log("  --issue requested but GITHUB_TOKEN is not set; issue NOT created.");
+	}
+}
+
+await main();

package/scripts/generate-models.ts

@@ -37,9 +37,35 @@ const PI_SUPPORTED_INPUT = new Set(["text", "image"]);
  * Manual corrections over models.dev live in scripts/manual-overrides.ts
  * (shared with test/generated-catalog.test.ts, which pins that every
  * override lands on the generated entry with its provenance note).
- * Capabilities diverging from models.dev are recorded there, never here.
+ * Capability divergences from models.dev are recorded there, never here.
+ * MANUAL_NOTES adds provenance-only notes to otherwise-untouched entries.
  */
-const MANUAL_NOTES: Record<string, string> = {};
+const MANUAL_NOTES: Record<string, string> = {
+	"qwen3.8-flash":
+		"contextWindow 262,144: the earlier 1,000,000 override (maintainer-confirmed 2026-09-05) was withdrawn 2026-09-07 — the updated https://nan.builders/docs/models still states '262K token context, the model's native window' and models.dev agrees at 262,144; NaN docs are treated as the most reliable source (maintainer instruction, 2026-09-07).",
+};
+
+/**
+ * Models the provider has removed but that models.dev may still list.
+ * Excluded at generation time with the recorded reason — a regeneration must
+ * never resurrect an entry the gateway no longer serves (this happened with
+ * glm5.2: hand-removed 2026-09-05, models.dev re-listed it by 2026-09-07).
+ */
+const PROVIDER_REMOVED_MODEL_IDS: Record<string, string> = {
+	"glm5.2":
+		"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",
+};
+
+/**
+ * Models the provider documents and serves but that cannot be emitted yet:
+ * absent from models.dev, or missing a limit no source documents. Flagged in
+ * the catalog metadata instead of invented (no-fabrication rule); keys with
+ * access still receive them live via the /models refresh with conservative
+ * placeholder limits (UNKNOWN_MODEL_LIMITS).
+ */
+const KNOWN_UNEMITTABLE_MODEL_NOTES: readonly string[] = [
+	"glm5.3: served by NaN on the GLM 5.3 premium tier (https://nan.builders/docs/models + https://nan.builders/openapi.json, checked 2026-09-07) but absent from models.dev, and no source documents its max output tokens — no entry is generated (no-fabrication rule); premium keys still get it live via the /models refresh with conservative placeholder limits",
+];
 
 /**
  * LiteLLM compat confirmed against the live api.nan.builders gateway by the
@@ -113,6 +139,10 @@ function normalizeInput(modalitiesInput: string[] | undefined, modelId: string):
 }
 
 function convertModel(modelId: string, m: ModelsDevModel): GeneratedModel | { skip: string } {
+	const removedReason = PROVIDER_REMOVED_MODEL_IDS[modelId];
+	if (removedReason) {
+		return { skip: `provider-removed: "${modelId}" excluded from the catalog (${removedReason})` };
+	}
 	const contextWindow = m.limit?.context;
 	const maxTokens = m.limit?.output;
 	if (typeof contextWindow !== "number" || contextWindow <= 0) {
@@ -195,6 +225,7 @@ async function main(): Promise<void> {
 	const fetchedAt = new Date().toISOString();
 	const allNotes = [
 		...skipped,
+		...KNOWN_UNEMITTABLE_MODEL_NOTES,
 		...new Set(entries.flatMap((entry) => entry.notes ?? [])),
 	];
 

package/scripts/manual-overrides.ts

@@ -38,10 +38,6 @@ export interface ManualModelOverride {
 export const MANUAL_OVERRIDES: Record<string, ManualModelOverride> = {
 	"deepseek-v4-flash": {
 		input: ["text", "image"],
-		note: "input includes image: NaN serves the Vision-Exp variant (confirmed at https://nan.builders/docs/models, 'takes images as input'); models.dev provider nan lists text only.",
-	},
-	"qwen3.8-flash": {
-		contextWindow: 1_000_000,
-		note: "contextWindow 1,000,000: maintainer-confirmed against api.nan.builders (2026-09-05); both models.dev and https://nan.builders/docs/models still listed 262,144 ('262K token context, the model's native window') as of 2026-09-05 — re-verify against the gateway/docs when they update.",
+		note: "input includes image: NaN serves the Vision-Exp variant ('takes images as input', https://nan.builders/docs/models, checked 2026-09-07; the image_url content-parts in https://nan.builders/openapi.json list deepseek-v4-flash among the vision models); models.dev provider nan lists text only.",
 	},
 };

package/scripts/models.generated.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by scripts/generate-models.ts
 // Do not edit manually — run `bun run generate-models` to update.
 //
-// Source: https://models.dev/api.json (provider "nan"), fetched 2026-09-05T11:34:28.187Z
+// Source: https://models.dev/api.json (provider "nan"), fetched 2026-09-08T22:49:12.806Z
 // 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.
@@ -36,7 +36,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, supportsUsageInStreaming true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested.",
-			"input includes image: NaN serves the Vision-Exp variant (confirmed at https://nan.builders/docs/models, 'takes images as input'); models.dev provider nan lists text only."
+			"input includes image: NaN serves the Vision-Exp variant ('takes images as input', https://nan.builders/docs/models, checked 2026-09-07; the image_url content-parts in https://nan.builders/openapi.json list deepseek-v4-flash among the vision models); models.dev provider nan lists text only."
 		],
 		"extras": {
 			"id": "deepseek-v4-flash",
@@ -133,62 +133,6 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			}
 		}
 	},
-	{
-		"id": "glm5.2",
-		"name": "GLM-5.2",
-		"reasoning": true,
-		"input": [
-			"text"
-		],
-		"cost": {
-			"input": 0,
-			"output": 0,
-			"cacheRead": 0,
-			"cacheWrite": 0
-		},
-		"contextWindow": 500000,
-		"maxTokens": 131072,
-		"compat": {
-			"supportsDeveloperRole": false,
-			"supportsReasoningEffort": true,
-			"supportsUsageInStreaming": true,
-			"maxTokensField": "max_tokens"
-		},
-		"notes": [
-			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, supportsUsageInStreaming true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested."
-		],
-		"extras": {
-			"id": "glm5.2",
-			"name": "GLM-5.2",
-			"description": "Open flagship GLM for long-horizon coding agents, served at 500K context on the NaN premium tier",
-			"family": "glm",
-			"attachment": false,
-			"reasoning": true,
-			"reasoning_options": [],
-			"tool_call": true,
-			"structured_output": true,
-			"temperature": true,
-			"release_date": "2026-06-13",
-			"last_updated": "2026-06-13",
-			"modalities": {
-				"input": [
-					"text"
-				],
-				"output": [
-					"text"
-				]
-			},
-			"open_weights": true,
-			"limit": {
-				"context": 500000,
-				"output": 131072
-			},
-			"cost": {
-				"input": 0,
-				"output": 0
-			}
-		}
-	},
 	{
 		"id": "glm5.3-flash",
 		"name": "GLM-5.3-Flash",
@@ -236,7 +180,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 					"text"
 				]
 			},
-			"open_weights": false,
+			"open_weights": true,
 			"limit": {
 				"context": 1000000,
 				"output": 131072
@@ -382,7 +326,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"cacheRead": 0,
 			"cacheWrite": 0
 		},
-		"contextWindow": 1000000,
+		"contextWindow": 262144,
 		"maxTokens": 131072,
 		"compat": {
 			"supportsDeveloperRole": false,
@@ -392,7 +336,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, supportsUsageInStreaming true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested.",
-			"contextWindow 1,000,000: maintainer-confirmed against api.nan.builders (2026-09-05); both models.dev and https://nan.builders/docs/models still listed 262,144 ('262K token context, the model's native window') as of 2026-09-05 — re-verify against the gateway/docs when they update."
+			"contextWindow 262,144: the earlier 1,000,000 override (maintainer-confirmed 2026-09-05) was withdrawn 2026-09-07 — the updated https://nan.builders/docs/models still states '262K token context, the model's native window' and models.dev agrees at 262,144; NaN docs are treated as the most reliable source (maintainer instruction, 2026-09-07)."
 		],
 		"extras": {
 			"id": "qwen3.8-flash",
@@ -431,12 +375,14 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 export const GENERATED_CATALOG_META = {
 	source: "https://models.dev/api.json",
 	modelsDevProvider: "nan",
-	fetchedAt: "2026-09-05T11:34:28.187Z",
-	modelCount: 7,
-	models: ["deepseek-v4-flash","gemma4","glm5.2","glm5.3-flash","mimo-v2.5","qwen3.6","qwen3.8-flash"],
+	fetchedAt: "2026-09-08T22:49:12.806Z",
+	modelCount: 6,
+	models: ["deepseek-v4-flash","gemma4","glm5.3-flash","mimo-v2.5","qwen3.6","qwen3.8-flash"],
 	notes: [
+	"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)",
+	"glm5.3: served by NaN on the GLM 5.3 premium tier (https://nan.builders/docs/models + https://nan.builders/openapi.json, checked 2026-09-07) but absent from models.dev, and no source documents its max output tokens — no entry is generated (no-fabrication rule); premium keys still get it live via the /models refresh with conservative placeholder limits",
 	"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, supportsUsageInStreaming true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested.",
-	"input includes image: NaN serves the Vision-Exp variant (confirmed at https://nan.builders/docs/models, 'takes images as input'); models.dev provider nan lists text only.",
-	"contextWindow 1,000,000: maintainer-confirmed against api.nan.builders (2026-09-05); both models.dev and https://nan.builders/docs/models still listed 262,144 ('262K token context, the model's native window') as of 2026-09-05 — re-verify against the gateway/docs when they update."
+	"input includes image: NaN serves the Vision-Exp variant ('takes images as input', https://nan.builders/docs/models, checked 2026-09-07; the image_url content-parts in https://nan.builders/openapi.json list deepseek-v4-flash among the vision models); models.dev provider nan lists text only.",
+	"contextWindow 262,144: the earlier 1,000,000 override (maintainer-confirmed 2026-09-05) was withdrawn 2026-09-07 — the updated https://nan.builders/docs/models still states '262K token context, the model's native window' and models.dev agrees at 262,144; NaN docs are treated as the most reliable source (maintainer instruction, 2026-09-07)."
 ],
 } as const;

package/src/fetch-models.ts

@@ -12,12 +12,16 @@
  *     only model `id`s — no capability fields. It is used solely to confirm
  *     which model IDs are currently live.
  *
- * Merge: live IDs × generated capability data. A live ID with no generated
- * match is kept with conservative placeholder limits (the same defaults used
- * in custom-provider.md's dynamic-discovery example) and no reasoning
- * support — capabilities stay "unknown", nothing is fabricated. On fetch
- * failure, timeout, or an unusable response, callers fall back to the
- * generated catalog so startup is never blocked.
+ * Merge: live IDs × generated capability data — an allowlist, not an open
+ * ingest. Only allowlisted IDs surface: a live ID with generated data keeps
+ * its generated capabilities, and an allowlisted uncatalogued ID (premium
+ * live-only) gets conservative placeholder limits (the same defaults used in
+ * custom-provider.md's dynamic-discovery example) with no reasoning support -
+ * capabilities stay "unknown", nothing is fabricated. Every other live ID is
+ * dropped so undocumented models (and any model NaN starts serving later)
+ * and non-chat endpoints never surface. On fetch failure, timeout, or an
+ * unusable response, callers fall back to the generated catalog so startup
+ * is never blocked.
  */
 
 import type { Model, OpenAICompletionsCompat } from "@earendil-works/pi-ai";
@@ -60,6 +64,28 @@ export const NAN_COMPAT_API = "openai-completions" as const;
  */
 export const UNKNOWN_MODEL_LIMITS = { contextWindow: 128_000, maxTokens: 4_096 } as const;
 
+/**
+ * The allowlist of model ids this package may surface. Everything a live
+ * /models response returns that is NOT here is dropped — so models that are
+ * undocumented (and might become available later, e.g. one NaN starts
+ * serving after a release) can never leak through the package.
+ *
+ * Every current chat model is listed: the six models.dev-documented entries
+ * plus the premium live-only glm5.3 (which NaN serves via /models but that
+ * models.dev omits — see the "unemittable" note in scripts/generate-models.ts).
+ * Non-chat endpoints (flux-2-klein, kokoro, whisper, qwen3-embedding, rerank)
+ * are deliberately excluded: they are MCP-bridge territory, not chat models.
+ */
+const ALLOWED_MODEL_IDS = [
+	"deepseek-v4-flash",
+	"gemma4",
+	"glm5.3-flash",
+	"glm5.3",
+	"mimo-v2.5",
+	"qwen3.6",
+	"qwen3.8-flash",
+] as const;
+
 /** Timeout for the live /models fetch; matches the pi-synthetic-provider precedent (~3s). */
 export const DEFAULT_MODELS_TIMEOUT_MS = 3_000;
 
@@ -87,9 +113,10 @@ export function toModel(entry: GeneratedModelEntry, source: CatalogSource): Mode
 	};
 }
 
-/** The generated fallback catalog as pi-ai Models for the given provider. */
+/** The generated fallback catalog as pi-ai Models for the given provider (allowlisted entries only). */
 export function baselineModels(source: CatalogSource): Model<"openai-completions">[] {
-	return NAN_GENERATED_MODELS.map((entry) => toModel(entry, source));
+	const allowed = new Set<string>(ALLOWED_MODEL_IDS);
+	return NAN_GENERATED_MODELS.filter((entry) => allowed.has(entry.id)).map((entry) => toModel(entry, source));
 }
 
 export interface LiveModelListOptions {
@@ -142,15 +169,17 @@ export interface MergedCatalog {
 	models: Model<"openai-completions">[];
 	/** Live IDs resolved against generated capability data. */
 	matched: string[];
-	/** Live IDs kept with unknown capabilities (conservative limits). */
+	/** Allowlisted live IDs kept with unknown capabilities (conservative limits). */
 	unknown: string[];
 }
 
 /**
- * Merge live model IDs with the generated capability catalog.
- * Known IDs get generated data; unknown IDs get conservative placeholder
- * limits, `reasoning: false`, and zero cost — documented defaults, not
- * invented capabilities.
+ * Merge live model IDs with the generated capability catalog, gated by the
+ * allowlist. Only allowlisted IDs surface: live IDs with generated data keep
+ * their generated capabilities; allowlisted uncatalogued IDs (glm5.3) get
+ * conservative placeholder limits, `reasoning: false`, and zero cost
+ * (documented defaults, not invented capabilities). Every non-allowlisted
+ * live ID is dropped.
  */
 export function mergeLiveWithGenerated(
 	liveIds: readonly string[],
@@ -158,11 +187,13 @@ export function mergeLiveWithGenerated(
 	generated: readonly GeneratedModelEntry[] = NAN_GENERATED_MODELS,
 ): MergedCatalog {
 	const byId = new Map(generated.map((entry) => [entry.id, entry]));
+	const allowed = new Set<string>(ALLOWED_MODEL_IDS);
 	const models: Model<"openai-completions">[] = [];
 	const matched: string[] = [];
 	const unknown: string[] = [];
 
 	for (const id of liveIds) {
+		if (!allowed.has(id)) continue;
 		const entry = byId.get(id);
 		if (entry) {
 			models.push(toModel(entry, source));
@@ -205,7 +236,7 @@ export interface ResolvedCatalog {
 	 * when the live fetch failed and the generated fallback was used.
 	 */
 	liveIds: Set<string> | undefined;
-	/** Live IDs kept with unknown capabilities (present only when liveIds is set). */
+	/** Allowlisted live IDs kept with unknown capabilities (present only when liveIds is set). */
 	unknownIds: string[];
 }
 

package/src/mcp/nan-media.ts

@@ -14,8 +14,8 @@
  *   other env vars inherit from your environment (generated files land in
  *   ~/nan-mcp-output/ by default).
  * - Version pinning follows the upstream server's own supply-chain guidance:
- *   NAN_MEDIA_MCP_VERSION (default "1.0.7"), or pass a custom command with
- *   NAN_MEDIA_MCP_COMMAND (space-separated, e.g. "bunx nan-mcp-server@1.0.7").
+ *   NAN_MEDIA_MCP_VERSION (default "1.0.8"), or pass a custom command with
+ *   NAN_MEDIA_MCP_COMMAND (space-separated, e.g. "bunx nan-mcp-server@1.0.8").
  */
 
 import { Type, type TSchema } from "@earendil-works/pi-ai";
@@ -28,7 +28,21 @@ export const NAN_MEDIA_MCP_ENV = "NAN_MEDIA_MCP";
 export const NAN_MEDIA_MCP_VERSION_ENV = "NAN_MEDIA_MCP_VERSION";
 export const NAN_MEDIA_MCP_COMMAND_ENV = "NAN_MEDIA_MCP_COMMAND";
 export const NAN_MEDIA_MCP_TIMEOUT_ENV = "NAN_MEDIA_MCP_TIMEOUT_MS";
-export const DEFAULT_NAN_MEDIA_MCP_VERSION = "1.0.7";
+export const DEFAULT_NAN_MEDIA_MCP_VERSION = "1.0.8";
+
+/**
+ * The MCP tool names on the stdio nan-mcp-server that this package bridges as
+ * pi tools. Kept as the single source of truth for the check script
+ * (scripts/check-nan-mcp-server.ts) and to type each spec's `mcpTool` so the
+ * bridge cannot drift from the set it claims to expose.
+ */
+export const NAN_MEDIA_MCP_SERVER_TOOLS = [
+	"generate_image",
+	"edit_image",
+	"text_to_speech",
+	"list_voices",
+	"speech_to_text",
+] as const;
 export const DEFAULT_MEDIA_MCP_TIMEOUT_MS = 120_000;
 
 /** Media tools bridged from the stdio MCP server (audio/image/transcription scope). */
@@ -84,7 +98,7 @@ function mediaMcpTimeoutMs(): number {
 
 interface MediaToolSpec<TParams extends TSchema = TSchema> {
 	name: (typeof NAN_MEDIA_TOOLS)[number];
-	mcpTool: string;
+	mcpTool: (typeof NAN_MEDIA_MCP_SERVER_TOOLS)[number];
 	label: string;
 	description: string;
 	promptSnippet: string;
@@ -129,7 +143,7 @@ function defineMediaTool<TParams extends TSchema>(spec: MediaToolSpec<TParams>):
 /**
  * Build the media tool set. Registered only when NAN_MEDIA_MCP=1 and the
  * runtime supports registerTool; execution spawns the MCP server per call.
- * Schemas mirror nan-mcp-server's zod input schemas (v1.0.7).
+ * Schemas mirror nan-mcp-server's zod input schemas (v1.0.8).
  */
 export function createNanMediaTools(): ToolDefinition[] {
 	return [
@@ -160,6 +174,8 @@ export function createNanMediaTools(): ToolDefinition[] {
 				prompt: Type.String({ description: "Description of the edit or transformation to apply" }),
 				images: Type.Array(Type.String(), {
 					description: "Absolute paths to reference image files (PNG, JPEG, WebP; up to 4, each < 25MB)",
+					minItems: 1,
+					maxItems: 4,
 				}),
 				size: sizeProperty(),
 				n: Type.Optional(Type.Integer({ description: "Number of images to generate (1-4). Default 1", minimum: 1, maximum: 4 })),

package/src/mcp/stdio-client.ts

@@ -18,7 +18,7 @@ const PROTOCOL_VERSION = "2024-11-05";
 const CLIENT_INFO = { name: "pi-nan-provider", version: "0.2.0" };
 
 export interface StdioMcpCallOptions {
-	/** Command to spawn, e.g. ["npx", "-y", "nan-mcp-server@1.0.7"]. */
+	/** Command to spawn, e.g. ["npx", "-y", "nan-mcp-server@1.0.8"]. */
 	command: readonly string[];
 	/** Extra environment for the child (merged over process.env). */
 	env?: Record<string, string | undefined>;