@gtrabanco/pi-nan-provider 0.5.2 → 0.6.2

package/AGENTS.md

@@ -115,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,8 +98,27 @@ 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 |
 
@@ -124,6 +143,7 @@ Notas (grabadas por entrada en `scripts/models.generated.ts`):
 - `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.
+- **Conformidad con el esquema estricto**: NaN valida cada payload de `/chat/completions` contra su propio esquema estricto ([openapi.json](https://nan.builders/openapi.json)) y devuelve HTTP 400 `Invalid request. Check your request parameters.` para formas no permitidas — p. ej. un mensaje `assistant` reenviado con un bloque `toolCall` dentro de `content`, un campo `reasoning_details` solo de OpenAI, campos a nivel superior no documentados como `store` / `stream_options`, o un **array vacío `tools: []`**. Por eso cada petición se reescribe con un saneador en el proveedor (`src/openai-compat-sanitizer.ts`, conectado vía `onPayload` en la fábrica compartida) para que siempre sea válida según el esquema, sin importar qué versión de pi-ai esté empaquetada:
 - **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,8 +98,27 @@ 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 |
 
@@ -124,6 +143,7 @@ Notes (recorded per entry in `scripts/models.generated.ts`):
 - `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.
+- **Strict schema conformance**: NaN validates every `/chat/completions` payload against its own strict schema ([openapi.json](https://nan.builders/openapi.json)) and returns HTTP 400 `Invalid request. Check your request parameters.` for disallowed shapes — e.g. a replayed `assistant` message with a `toolCall` block inside `content`, an OpenAI-only `reasoning_details` field, undocumented top-level fields like `store` / `stream_options`, or an **empty `tools: []` array**. Every request is therefore rewritten by a provider-side sanitizer (`src/openai-compat-sanitizer.ts`, wired through the shared factory's `onPayload`) so it is always schema-valid no matter which pi-ai version is bundled:
 - **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.2",
+	"version": "0.6.2",
 	"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

@@ -80,11 +80,12 @@ const NAN_COMPAT = {
 	supportsDeveloperRole: false,
 	supportsReasoningEffort: true,
 	supportsUsageInStreaming: true,
+	supportsFinishReason: false,
 	maxTokensField: "max_tokens" as const,
 };
 
 const NAN_COMPAT_NOTE =
-	"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.";
+	"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. supportsFinishReason false added 2026-09-08: the LiteLLM gateway intermittently cuts SSE streams before emitting finish_reason (observed on glm5.3-flash, ~2026-09-08), and with the default true pi-ai throws 'Stream ended without finish_reason'; false makes pi-ai treat those truncated streams as stop/toolUse instead of erroring.";
 
 interface ModelsDevModel {
 	id?: string;

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-07T12:31:36.901Z
+// Source: https://models.dev/api.json (provider "nan"), fetched 2026-09-09T23:52:27.718Z
 // 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.
@@ -32,10 +32,11 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
 			"supportsUsageInStreaming": true,
+			"supportsFinishReason": false,
 			"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.",
+			"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. supportsFinishReason false added 2026-09-08: the LiteLLM gateway intermittently cuts SSE streams before emitting finish_reason (observed on glm5.3-flash, ~2026-09-08), and with the default true pi-ai throws 'Stream ended without finish_reason'; false makes pi-ai treat those truncated streams as stop/toolUse instead of erroring.",
 			"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": {
@@ -91,10 +92,11 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
 			"supportsUsageInStreaming": true,
+			"supportsFinishReason": false,
 			"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."
+			"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. supportsFinishReason false added 2026-09-08: the LiteLLM gateway intermittently cuts SSE streams before emitting finish_reason (observed on glm5.3-flash, ~2026-09-08), and with the default true pi-ai throws 'Stream ended without finish_reason'; false makes pi-ai treat those truncated streams as stop/toolUse instead of erroring."
 		],
 		"extras": {
 			"id": "gemma4",
@@ -153,10 +155,11 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
 			"supportsUsageInStreaming": true,
+			"supportsFinishReason": false,
 			"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."
+			"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. supportsFinishReason false added 2026-09-08: the LiteLLM gateway intermittently cuts SSE streams before emitting finish_reason (observed on glm5.3-flash, ~2026-09-08), and with the default true pi-ai throws 'Stream ended without finish_reason'; false makes pi-ai treat those truncated streams as stop/toolUse instead of erroring."
 		],
 		"extras": {
 			"id": "glm5.3-flash",
@@ -180,7 +183,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 					"text"
 				]
 			},
-			"open_weights": false,
+			"open_weights": true,
 			"limit": {
 				"context": 1000000,
 				"output": 131072
@@ -211,10 +214,11 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
 			"supportsUsageInStreaming": true,
+			"supportsFinishReason": false,
 			"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."
+			"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. supportsFinishReason false added 2026-09-08: the LiteLLM gateway intermittently cuts SSE streams before emitting finish_reason (observed on glm5.3-flash, ~2026-09-08), and with the default true pi-ai throws 'Stream ended without finish_reason'; false makes pi-ai treat those truncated streams as stop/toolUse instead of erroring."
 		],
 		"extras": {
 			"id": "mimo-v2.5",
@@ -270,10 +274,11 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
 			"supportsUsageInStreaming": true,
+			"supportsFinishReason": false,
 			"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."
+			"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. supportsFinishReason false added 2026-09-08: the LiteLLM gateway intermittently cuts SSE streams before emitting finish_reason (observed on glm5.3-flash, ~2026-09-08), and with the default true pi-ai throws 'Stream ended without finish_reason'; false makes pi-ai treat those truncated streams as stop/toolUse instead of erroring."
 		],
 		"extras": {
 			"id": "qwen3.6",
@@ -332,10 +337,11 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"supportsDeveloperRole": false,
 			"supportsReasoningEffort": true,
 			"supportsUsageInStreaming": true,
+			"supportsFinishReason": false,
 			"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.",
+			"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. supportsFinishReason false added 2026-09-08: the LiteLLM gateway intermittently cuts SSE streams before emitting finish_reason (observed on glm5.3-flash, ~2026-09-08), and with the default true pi-ai throws 'Stream ended without finish_reason'; false makes pi-ai treat those truncated streams as stop/toolUse instead of erroring.",
 			"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": {
@@ -375,13 +381,13 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 export const GENERATED_CATALOG_META = {
 	source: "https://models.dev/api.json",
 	modelsDevProvider: "nan",
-	fetchedAt: "2026-09-07T12:31:36.901Z",
+	fetchedAt: "2026-09-09T23:52:27.718Z",
 	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.",
+	"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. supportsFinishReason false added 2026-09-08: the LiteLLM gateway intermittently cuts SSE streams before emitting finish_reason (observed on glm5.3-flash, ~2026-09-08), and with the default true pi-ai throws 'Stream ended without finish_reason'; false makes pi-ai treat those truncated streams as stop/toolUse instead of erroring.",
 	"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)."
 ],

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,16 +187,25 @@ 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));
 			matched.push(id);
 		} else {
+			// Conservative placeholder for allowlisted uncatalogued live ids
+			// (e.g. premium glm5.3): limits are the documented safe envelope and
+			// capabilities stay "unknown". supportsFinishReason: false is NOT a
+			// capability claim — it is a client-tolerance flag for the same
+			// gateway-level SSE truncation handled in NAN_COMPAT (LiteLLM cutting
+			// streams before finish_reason); without it pi-ai throws "Stream
+			// ended without finish_reason" on those models too.
 			models.push({
 				id,
 				name: id,
@@ -179,6 +217,7 @@ export function mergeLiveWithGenerated(
 				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
 				contextWindow: UNKNOWN_MODEL_LIMITS.contextWindow,
 				maxTokens: UNKNOWN_MODEL_LIMITS.maxTokens,
+				compat: { supportsFinishReason: false },
 			});
 			unknown.push(id);
 		}
@@ -205,7 +244,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>;

package/src/openai-compat-sanitizer.ts

@@ -0,0 +1,242 @@
+/**
+ * Strict OpenAI Chat Completions schema conformance for NaN-compatible
+ * providers.
+ *
+ * NaN's gateway returns HTTP 400 `Invalid request. Check your request parameters.`
+ * for any request that does not match the schema it publishes at
+ * https://nan.builders/openapi.json (checked 2026-09-09). That schema is
+ * stricter than the permissive OpenAI shape models like OpenAI/Anthropic
+ * tolerate, and it does NOT match what pi-ai's message transformer emits in
+ * every case. This module rewrites the outgoing `/chat/completions` payload
+ * so it is always schema-valid, no matter which pi-ai version is bundled or
+ * how the history was constructed.
+ *
+ * The violated shapes we correct (each one traced to NaN's schema):
+ *
+ *  1. An `assistant` message whose `content` ARRAY contains a `toolCall`
+ *     block. NaN's `ContentPart` oneOf allows ONLY `{type:"text"}` and
+ *     `{type:"image_url"}` parts; a tool call is rejected. Tool calls must
+ *     live in the top-level `tool_calls` field:
+ *     `{ id, type:"function", function:{ name, arguments } }` with
+ *     `arguments` as a JSON-encoded string. (This is the shape reported in
+ *     the issue: a replayed assistant message with a `toolCall` block still
+ *     inside `content` → 400.)
+ *  2. An `assistant` message carrying `reasoning_details`. NaN's `Message`
+ *     schema admits `role/content/name/tool_calls/tool_call_id/reasoning_content`
+ *     but NOT `reasoning_details` (an OpenAI-specific field pi-ai emits on
+ *     same-model replay of encrypted/text reasoning signatures). That field
+ *     is stripped; reasoning content is delivered the way NaN understands it
+ *     (`reasoning_content`, or as plain text already present in `content`).
+ *  3. A `content` array containing an unknown part type (e.g. `thinking`).
+ *     NaN only accepts `text` and `image_url`; other types are dropped, and
+ *     thinking text is folded into a `text` part so the model's reasoning is
+ *     not silently lost.
+ *  4. Top-level fields NaN's schema does not list: `store` and
+ *     `stream_options`. These are opt-in/usage fields pi-ai sends by default
+ *     for a "standard" provider; NaN does not document them, so they are
+ *     removed. (Removing `stream_options` only costs live token-usage in the
+ *     stream; NaN models are membership-quota based with zero per-token cost,
+ *     so this is a safe trade.)
+ *  5. An EMPTY `tools` array. Verified against the live gateway (2026-09-09):
+ *     NaN rejects `tools: []` with the same 400, while `stream: true`, a
+ *     `system` message, string content, and a `tool` role message are all
+ *     accepted. pi-ai emits `tools: []` when the conversation has tool-call
+ *     history but no active tools; NaN only accepts a real tool list, so the
+ *     empty array is dropped and a non-empty list is kept.
+ *
+ * This is applied by wrapping the provider's api `stream`/`streamSimple`
+ * with an `onPayload` hook in src/provider-factory.ts, so every provider
+ * registered through the shared factory stays schema-valid. A user-supplied
+ * `onPayload` (if pi or a consumer passes one) is preserved and chained
+ * after sanitization.
+ */
+
+interface ContentPart {
+	type?: unknown;
+	text?: unknown;
+	thinking?: unknown;
+	[m: string]: unknown;
+}
+
+interface ToolCallBlock {
+	id?: unknown;
+	name?: unknown;
+	arguments?: unknown;
+	[m: string]: unknown;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Monotonic counter for deterministic fallback tool-call ids (pi-ai always supplies ids; this is pure defense). */
+let anonymousToolCallSeq = 0;
+
+/** Normalize a `toolCall` content block into NaN's `tool_calls[].{id,type,function}` shape. */
+function toToolCall(block: ToolCallBlock): Record<string, unknown> {
+	const rawArgs = block.arguments;
+	let argumentsJson: string;
+	if (typeof rawArgs === "string") {
+		argumentsJson = rawArgs;
+	} else {
+		try {
+			argumentsJson = JSON.stringify(rawArgs ?? {});
+		} catch {
+			argumentsJson = "{}";
+		}
+	}
+	const fallbackName = typeof block.name === "string" && block.name.length > 0 ? block.name : "function";
+	return {
+		id: typeof block.id === "string" && block.id.length > 0 ? block.id : `call_${fallbackName}_${++anonymousToolCallSeq}`,
+		type: "function",
+		function: {
+			name: fallbackName,
+			arguments: argumentsJson,
+		},
+	};
+}
+
+/** Merge tool calls, de-duplicating by id and preferring the pre-existing (pi-ai-built) entries. */
+function mergeToolCalls(existing: unknown[], incoming: Array<Record<string, unknown>>): Array<Record<string, unknown>> {
+	const byId = new Map<string, Record<string, unknown>>();
+	for (const tc of existing) {
+		if (isObject(tc) && typeof tc.id === "string") byId.set(tc.id, tc);
+	}
+	for (const tc of incoming) {
+		if (typeof tc.id === "string" && !byId.has(tc.id)) byId.set(tc.id, tc);
+	}
+	return [...byId.values()];
+}
+
+/**
+ * Rebuild an assistant `content` value from an array of sanitized parts.
+ * NaN follows the OpenAI convention: a plain string when there is only text,
+ * an array of `text`/`image_url` parts when there are images, and `null` when
+ * there is no content (valid on an assistant message that returns tool calls).
+ */
+function normalizeAssistantContent(parts: Array<Record<string, unknown>>): string | Array<unknown> | null {
+	if (parts.length === 0) return null;
+	const allText = parts.every((part) => part.type === "text");
+	if (allText) {
+		const text = parts
+			.map((part) => (typeof part.text === "string" ? part.text : ""))
+			.join("");
+		return text.length > 0 ? text : null;
+	}
+	return parts;
+}
+
+/** Permit only NaN's approved content-part types; fold `thinking` into text. */
+function sanitizeAssistantContentPart(part: unknown): Record<string, unknown> | undefined {
+	if (!isObject(part)) return undefined;
+	const type = part.type;
+	if (type === "text") {
+		return { type: "text", text: typeof part.text === "string" ? part.text : String(part.text ?? "") };
+	}
+	if (type === "image_url") {
+		return { type: "image_url", image_url: part.image_url };
+	}
+	if (type === "thinking") {
+		const thinking = typeof part.thinking === "string" ? part.thinking : "";
+		if (thinking.trim().length === 0) return undefined;
+		return { type: "text", text: thinking };
+	}
+	// Anything else (toolCall handled separately, unknown types dropped) — NaN rejects it.
+	return undefined;
+}
+
+/** Sanitize a single message against NaN's strict schema. */
+function sanitizeMessage(message: unknown): unknown {
+	if (!isObject(message)) return message;
+	if (message.role !== "assistant") return message;
+
+	const out: Record<string, unknown> = { ...message };
+	delete out.reasoning_details; // OpenAI-only; absent from NaN's Message schema.
+	// NaN understands `reasoning_content` (not the generic `reasoning` field), so
+	// carry any reasoning text over to the field NaN accepts rather than dropping it.
+	if (out.reasoning !== undefined && out.reasoning_content === undefined) {
+		out.reasoning_content = out.reasoning;
+	}
+	delete out.reasoning;
+
+	const content = message.content;
+	if (!Array.isArray(content)) return out; // string / null content is already schema-valid.
+
+	const textParts: Array<Record<string, unknown>> = [];
+	const toolCallBlocks: ToolCallBlock[] = [];
+	for (const part of content) {
+		if (isObject(part) && part.type === "toolCall") {
+			toolCallBlocks.push(part as unknown as ToolCallBlock);
+			continue;
+		}
+		const sanitized = sanitizeAssistantContentPart(part);
+		if (sanitized) textParts.push(sanitized);
+	}
+
+	out.content = normalizeAssistantContent(textParts);
+
+	const existingToolCalls = Array.isArray(message.tool_calls) ? message.tool_calls : [];
+	const toolCalls = toolCallBlocks.length > 0 ? mergeToolCalls(existingToolCalls, toolCallBlocks.map(toToolCall)) : [...existingToolCalls];
+	if (toolCalls.length > 0) out.tool_calls = toolCalls;
+	else delete out.tool_calls;
+
+	return out;
+}
+
+/**
+ * Rewrite an OpenAI-compatible `/chat/completions` payload so every field
+ * conforms to NaN's published schema. Returns the updated payload; if the
+ * payload has no `messages` array it is returned unchanged.
+ */
+export function sanitizeOpenAICompatPayload(payload: unknown): unknown {
+	if (!isObject(payload) || !Array.isArray(payload.messages)) return payload;
+
+	const messages = payload.messages.map(sanitizeMessage);
+	const out: Record<string, unknown> = { ...payload, messages };
+
+	// Patch function-tools call arguments: NaN wants function-call arguments
+	// serialized as a JSON string under `function.arguments`. pi-ai already does
+	// this, but a hand-built / older-version payload may not. Normalize each.
+	if (Array.isArray(out.messages)) {
+		out.messages = out.messages.map((m) => {
+			if (!isObject(m) || m.role !== "assistant") return m;
+			if (!Array.isArray(m.tool_calls)) return m;
+			const normalized = m.tool_calls.map((tc) => {
+				if (!isObject(tc)) return tc;
+				if (typeof tc.type === "string" && tc.type !== "function") return tc;
+				const fn = isObject(tc.function) ? tc.function : {};
+				let args = fn.arguments;
+				if (args !== undefined && typeof args !== "string") {
+					try {
+						args = JSON.stringify(args);
+					} catch {
+						args = "{}";
+					}
+				}
+				return { ...tc, type: "function", function: { ...fn, ...(args !== undefined ? { arguments: args } : {}) } };
+			});
+			return { ...m, tool_calls: normalized };
+		});
+	}
+
+	// Top-level fields absent from NaN's schema.
+	delete out.store;
+	delete out.stream_options;
+	// NaN documents `max_tokens`, not `max_completion_tokens`.
+	if ("max_completion_tokens" in out && !("max_tokens" in out)) {
+		out.max_tokens = out.max_completion_tokens;
+		delete out.max_completion_tokens;
+	}
+	// NaN rejects an EMPTY `tools` array with HTTP 400 `Invalid request. Check
+	// your request parameters.` (verified against the live gateway 2026-09-09:
+	// everything else in the payload — stream/system/content-as-string/tool role
+	// — is accepted, but `tools: []` is not). pi-ai emits `tools: []` whenever
+	// the conversation has tool-call history but no active tools; NaN only
+	// accepts a real tool list, so drop the empty array. A non-empty `tools`
+	// list is preserved unchanged.
+	if (Array.isArray(out.tools) && out.tools.length === 0) {
+		delete out.tools;
+	}
+
+	return out;
+}

package/src/provider-factory.ts

@@ -32,6 +32,7 @@ import {
 	resolveCatalog,
 	type CatalogSource,
 } from "./fetch-models.ts";
+import { sanitizeOpenAICompatPayload } from "./openai-compat-sanitizer.ts";
 
 export interface OpenAICompatibleProviderConfig {
 	/** Provider id as registered in pi, e.g. "nan". */
@@ -80,6 +81,48 @@ export async function resolveOpenAICompletionsApi(): Promise<OpenAICompletionsAp
 	return cachedApiFactory;
 }
 
+/**
+ * Wrap an api so every outgoing `/chat/completions` payload is made conformant
+ * to the strict OpenAI Chat Completions schema NaN enforces (see
+ * ./openai-compat-sanitizer.ts). NaN returns HTTP 400 `Invalid request. Check
+ * your request parameters.` for any payload that violates it — including a
+ * replayed assistant message with a `toolCall` block inside `content`, a
+ * `reasoning_details` field, or undocumented top-level fields like `store` /
+ * `stream_options`. Sanitizing via the `onPayload` hook works regardless of
+ * which pi-ai version the runtime bundles, so the fix is not tied to a
+ * specific upstream build.
+ *
+ * Any caller-supplied `onPayload` (e.g. pi's own debug/passthrough hook) is
+ * preserved and chained AFTER sanitization, so the final payload is always
+ * schema-valid.
+ */
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+export function wrapApiForStrictSanitization(api: ProviderStreams): ProviderStreams {
+	const withSanitizer = <TOptions extends object | undefined>(options: TOptions): TOptions => {
+		const userOnPayload = isObject(options) ? (options.onPayload as unknown) : undefined;
+		return {
+			...((options ?? {}) as Record<string, unknown>),
+			onPayload: async (payload: unknown, model: unknown) => {
+				const sanitized = sanitizeOpenAICompatPayload(payload);
+				if (typeof userOnPayload === "function") {
+					const userResult = await (userOnPayload as (p: unknown, m: unknown) => unknown)(sanitized, model);
+					return userResult ?? sanitized;
+				}
+				return sanitized;
+			},
+		} as TOptions;
+	};
+
+	return {
+		...api,
+		stream: (model, context, options) => api.stream(model, context, withSanitizer(options)),
+		streamSimple: (model, context, options) => api.streamSimple(model, context, withSanitizer(options)),
+	};
+}
+
 /**
  * Build a complete pi-ai Provider for an OpenAI-compatible endpoint:
  *
@@ -130,6 +173,6 @@ export async function createNanCompatibleProvider(
 			const current = liveIds;
 			return current ? models.filter((model) => current.has(model.id)) : models;
 		},
-		api: apiFactory(),
+		api: wrapApiForStrictSanitization(apiFactory()),
 	});
 }