@gtrabanco/pi-nan-provider 0.6.1 → 0.6.2

package/README.es.md

@@ -143,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

@@ -143,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.6.1",
+	"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",

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-08T22:49:12.806Z
+// 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",
@@ -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-08T22:49:12.806Z",
+	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

@@ -199,6 +199,13 @@ export function mergeLiveWithGenerated(
 			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,
@@ -210,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);
 		}

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()),
 	});
 }