@maheidem/model-discovery 0.7.0 → 0.7.1

package/README.md

@@ -207,6 +207,68 @@ If Pi has an `enabledModels` scope, press **Tab** in `/model` to switch from sco
 
 Profiles are retained if a model temporarily disappears during a re-scan.
 
+## Tool-schema repair (local endpoints)
+
+llama.cpp's JSON-schema→grammar converter — the one behind llama.cpp, llama-swap, LM
+Studio, and LiteLLM routes that forward to them — resolves `$ref` pointers **only
+against the root of a tool schema document**. MCP servers that build schemas by nesting
+Pydantic `model_json_schema()` output inside a hand-written parent routinely leave
+`$defs` on an inner node while the `$ref`s inside it stay root-relative:
+
+```jsonc
+{ "properties": { "patch": {
+    "$defs": { "GuidelineMetricInput": { /* ... */ } },        // defs live here
+    "properties": { "metrics": { "items": { "$ref": "#/$defs/GuidelineMetricInput" } } }
+}}}
+```
+
+The pointer resolves against the document root, where `$defs` is not — so the server
+rejects the **entire request**:
+
+```text
+HTTP 400 {"code":400,"message":"JSON schema conversion failed:
+          Error resolving ref #/$defs/GuidelineMetricInput: $defs not in {...}"}
+```
+
+Because the offending tool rides along in every tool list, *every* message in the
+session fails, which looks like a broken endpoint, proxy, or model discovery rather
+than a bad upstream schema.
+
+A second llama.cpp b10612 bug was verified independently: `maxLength: 2000` below
+an array's `items` schema produces `Failed to initialize samplers: failed to parse
+grammar`, while 1999, 2001, and even 65536 all compile. This affected the
+`okto_pulse_move_card` tool even before any `$ref` repair.
+
+For self-hosted endpoints (private/loopback URL, or a detected local engine) the
+extension normalises outgoing tool schemas in `before_provider_request`:
+
+- `$defs` / `definitions` found at any depth are hoisted to a root registry, with
+collisions de-duplicated and local refs rewritten to match;
+- every `$ref` is inlined iteratively, so refs-to-refs collapse;
+- unresolvable or recursive `$ref`s become permissive nodes instead of a hard 400;
+- `$ref` / `$defs` never reach the wire, and annotation siblings (`description`,
+`title`) are preserved;
+- the exact nested-array `maxLength: 2000` failure is sent as 2001. This is the
+least-permissive working neighbour; the MCP server still validates its real 2000 limit.
+
+Cloud APIs and clean payloads are left byte-identical (the payload object's identity is
+returned, no cloning). Repairing a 521-tool catalogue costs ~1.5 ms. Opt out per
+provider with `"repairToolSchemas": false` in `~/.pi/agent/model-discovery.json`, or
+globally with `PI_MODEL_DISCOVERY_NO_SCHEMA_REPAIR=1`. Each distinct repair is logged
+once as `[model-discovery] <provider>: repaired N local tool schema(s): …`.
+
+Live verification against llama-swap v251 → llama.cpp b10612: the raw 521-tool MCP
+catalogue returned HTTP 400; all 16 affected schemas were repaired in flight; the same
+request then returned HTTP 200 with no residual `$ref`/`$defs` on the wire.
+
+Verification:
+
+```bash
+npm test                                              # includes schema-repair.test.ts
+node --experimental-strip-types scripts/live-schema-repair-check.ts http://HOST
+node --experimental-strip-types scripts/bisect-grammar.ts http://HOST MODEL FILTER
+```
+
 ## Offline resilience
 
 Every successful live scan atomically persists the raw model catalogue as the source's last known-good cache. Saved sources are scanned independently and concurrently at startup. If one source is offline, times out, rejects its credentials, or returns a malformed response:

package/index.ts

@@ -46,6 +46,12 @@ import {
 	redactSecret,
 	type ModelConfig,
 } from "./providers.ts";
+import {
+	describeToolSchemaRepair,
+	isLocalEndpointUrl,
+	repairRequestToolSchemas,
+	type ToolSchemaRepairReport,
+} from "./schema-repair.ts";
 import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import os from "node:os";
@@ -73,6 +79,12 @@ interface DiscoveredProvider {
 	profileSchemaVersion?: number;
 	cachedModels?: Record<string, unknown>[];
 	compat?: Record<string, unknown>;
+	/**
+	 * Inline $defs/$ref in outgoing tool schemas for this endpoint (default: true for
+	 * local/self-hosted endpoints, where llama.cpp-style grammar converters reject any
+	 * $ref that is not resolvable at the document root). Set false to send verbatim.
+	 */
+	repairToolSchemas?: boolean;
 	/** Last successful live catalogue refresh (legacy name retained in storage). */
 	lastScanned?: number;
 	lastScanAttempt?: number;
@@ -267,8 +279,36 @@ export default async function (pi: ExtensionAPI) {
 	};
 	const thinkingRoutes = new Map<string, RuntimeThinkingRoutes>();
 	const fixedProfileLabels = new Map<string, string>();
+	/** Providers whose outgoing tool schemas get local grammar compatibility repair. */
+	const schemaRepairProviders = new Set<string>();
+	/** Repair notices already surfaced, so a per-request hook never spams the log. */
+	const schemaRepairNotices = new Set<string>();
 	const routeKey = (providerName: string, modelId: string): string => `${providerName}/${modelId}`;
 
+	/**
+	 * llama.cpp (and llama-swap / LM Studio / LiteLLM routes that forward to it) has
+	 * strict JSON-schema→grammar compatibility limits: root-scoped $ref resolution and,
+	 * in b10612, one exact nested maxLength parser failure. A single incompatible MCP
+	 * tool makes *every* message 400. Local endpoints get their schemas normalised;
+	 * cloud APIs stay byte-identical. See schema-repair.ts.
+	 */
+	function shouldRepairToolSchemas(provider: DiscoveredProvider, serverType: string): boolean {
+		if (provider.repairToolSchemas === false) return false;
+		if (process.env.PI_MODEL_DISCOVERY_NO_SCHEMA_REPAIR) return false;
+		if (provider.repairToolSchemas === true) return true;
+		const LOCAL_ENGINES = ["llama.cpp", "oMLX", "Ollama", "vLLM", "SGLang", "LM Studio", "llama-swap"];
+		return LOCAL_ENGINES.some((needle) => serverType.toLowerCase().includes(needle.toLowerCase())) || isLocalEndpointUrl(provider.baseUrl);
+	}
+
+	function noteToolSchemaRepair(providerName: string, report: ToolSchemaRepairReport): void {
+		if (!report.changed) return;
+		const summary = describeToolSchemaRepair(report);
+		const signature = `${providerName}::${summary}`;
+		if (schemaRepairNotices.has(signature)) return;
+		schemaRepairNotices.add(signature);
+		console.error(`[model-discovery] ${providerName}: ${summary}`);
+	}
+
 	// -----------------------------------------------------------------------
 	// Provider registration with Pi's model registry
 	// -----------------------------------------------------------------------
@@ -291,6 +331,8 @@ export default async function (pi: ExtensionAPI) {
 		if (serverType === "llama.cpp" || serverType === "oMLX" || serverType === "Ollama") {
 			if (compat.supportsDeveloperRole === undefined) compat.supportsDeveloperRole = false;
 		}
+		if (shouldRepairToolSchemas(provider, serverType)) schemaRepairProviders.add(provider.name);
+		else schemaRepairProviders.delete(provider.name);
 		if (serverType === "oMLX") {
 			// Preserve the pre-profile base-model behavior. Fixed and adaptive profile
 			// aliases supply their own complete chat-template kwargs independently.
@@ -414,9 +456,27 @@ export default async function (pi: ExtensionAPI) {
 	}
 
 	pi.on("before_provider_request", (event, ctx) => {
+		let payload: unknown = event.payload;
+		let touched = false;
+
 		const active = activeThinkingRoute(ctx);
-		if (!active) return undefined;
-		return applyThinkingProfileRoute(event.payload, active.profile, active.runtime.repetitionPenaltyKey);
+		if (active) {
+			payload = applyThinkingProfileRoute(payload, active.profile, active.runtime.repetitionPenaltyKey);
+			touched = true;
+		}
+
+		// Repair local tool schemas so llama.cpp-style grammar converters accept them.
+		const providerName = ctx.model?.provider;
+		if (providerName && schemaRepairProviders.has(providerName)) {
+			const repaired = repairRequestToolSchemas(payload);
+			if (repaired.report.changed) {
+				noteToolSchemaRepair(providerName, repaired.report);
+				payload = repaired.payload;
+				touched = true;
+			}
+		}
+
+		return touched ? payload : undefined;
 	});
 
 	const updateThinkingProfileStatus = (ctx: ExtensionContext): void => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maheidem/model-discovery",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "type": "module",
   "description": "Interactive TUI for discovering local AI endpoints and defining named thinking/sampling profiles (llama.cpp, oMLX, Ollama, vLLM, SGLang, LM Studio).",
   "keywords": [
@@ -19,7 +19,7 @@
     "url": "https://github.com/maheidem/model-discovery/issues"
   },
   "scripts": {
-    "test": "node --experimental-strip-types --test profiles.test.ts offline.test.ts enrichment.test.ts"
+    "test": "node --experimental-strip-types --test profiles.test.ts offline.test.ts enrichment.test.ts schema-repair.test.ts"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.84.0",

package/schema-repair.ts

@@ -0,0 +1,473 @@
+/**
+ * Tool-schema repair for self-hosted OpenAI-compatible backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * llama.cpp's `json_schema_to_grammar` (the converter behind llama.cpp, llama-swap,
+ * LM Studio, and LiteLLM routes that forward to them) resolves `$ref` pointers
+ * **only against the root of the tool schema document**. MCP servers commonly build
+ * tool schemas by nesting Pydantic `model_json_schema()` output inside a hand-written
+ * parent schema, which leaves `$defs` sitting on an inner node while the `$ref`s
+ * inside it stay root-relative:
+ *
+ *   { "properties": { "patch": {
+ *       "$defs": { "GuidelineMetricInput": { ... } },        // defs live HERE
+ *       "properties": { "metrics": { "items": { "$ref": "#/$defs/GuidelineMetricInput" } } }
+ *   }}}
+ *
+ * The pointer says "document root", but `$defs` is not at the root, so llama.cpp
+ * rejects the whole request:
+ *
+ *   HTTP 400 {"code":400,"message":"JSON schema conversion failed:
+ *             Error resolving ref #/$defs/GuidelineMetricInput: $defs not in {...}"}
+ *
+ * The broken tool rides along in the tool list, so *every* message in the session
+ * fails — which looks like the endpoint, the proxy, or model discovery is broken.
+ *
+ * Verified live against llama-swap v251 -> llama.cpp b10612:
+ *   nested `$defs` + root-relative `$ref` -> HTTP 400 (the failure above)
+ *   `$defs` hoisted to document root      -> HTTP 200 (~15 s grammar compile)
+ *   `$ref`s fully inlined, no `$defs`    -> HTTP 200 (fast; what this module does)
+ *
+ * That build has a second, exact converter bug: a string with `maxLength: 2000`
+ * below an array's `items` schema produces "Failed to initialize samplers: failed
+ * to parse grammar". The neighbouring values 1999 and 2001, and even 65536, work.
+ * The wire schema therefore uses 2001 at that exact position; the MCP server remains
+ * the source of truth and still validates the real 2000-character limit.
+ *
+ * BEHAVIOUR
+ * ---------
+ * `repairRequestToolSchemas(payload)` normalises every tool schema in an outgoing
+ * /chat/completions payload:
+ *   1. `$defs` / `definitions` found at ANY depth are hoisted to a root registry
+ *      (name collisions are de-duplicated, local refs rewritten to match);
+ *   2. every `$ref` is inlined, iteratively, so refs-to-refs collapse;
+ *   3. unresolvable or cyclic refs become permissive nodes instead of a hard 400;
+ *   4. `$defs` / `definitions` / `$ref` never reach the wire;
+ *   5. nested-array `maxLength: 2000` is changed to 2001 for llama.cpp grammar
+ *      compatibility (only that exact, proven-broken value).
+ *
+ * No-op (original object identity, zero cloning) when nothing needs repairing.
+ */
+
+export interface ToolSchemaRepairReport {
+	/** Names of tools whose parameters schema was rewritten. */
+	repairedTools: string[];
+	/** `$ref` targets that could not be resolved; loosened to accept anything. */
+	droppedRefs: string[];
+	/** `$ref` targets forming a cycle; loosened to accept anything. */
+	cyclicRefs: string[];
+	/** Exact nested-array maxLength=2000 occurrences changed to 2001. */
+	adjustedGrammarLimits: number;
+	/** True when the payload was replaced (false = original identity kept). */
+	changed: boolean;
+}
+
+const EMPTY_REPORT: ToolSchemaRepairReport = {
+	repairedTools: [],
+	droppedRefs: [],
+	cyclicRefs: [],
+	adjustedGrammarLimits: 0,
+	changed: false,
+};
+
+const NOTICE_LIMIT = 6;
+const MAX_DEPTH = 512;
+export const LLAMA_CPP_BROKEN_NESTED_MAX_LENGTH = 2000;
+export const LLAMA_CPP_SAFE_NESTED_MAX_LENGTH = 2001;
+
+const DEFS_KEYWORDS = ["$defs", "definitions"];
+const REF_KEYWORDS = ["$ref"];
+
+/** Keywords whose value is a single subschema. */
+const SCHEMA_KEYWORDS = new Set([
+	"items",
+	"additionalItems",
+	"additionalProperties",
+	"unevaluatedItems",
+	"unevaluatedProperties",
+	"contains",
+	"propertyNames",
+	"if",
+	"then",
+	"else",
+	"not",
+]);
+
+/** Keywords whose value is an array of subschemas. */
+const SCHEMA_ARRAY_KEYWORDS = new Set(["anyOf", "oneOf", "allOf", "prefixItems"]);
+
+/** Keywords whose value is a map of name -> subschema. */
+const SCHEMA_MAP_KEYWORDS = new Set(["properties", "patternProperties", "dependentSchemas"]);
+
+type Rec = Record<string, unknown>;
+
+function isRecord(value: unknown): value is Rec {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function fingerprint(value: unknown): string {
+	return JSON.stringify(value) ?? "";
+}
+
+// ---------------------------------------------------------------------------
+// Detection (fast path)
+// ---------------------------------------------------------------------------
+
+export function schemaNeedsRepair(node: unknown, depth = 0, insideArrayItem = false): boolean {
+	if (depth > MAX_DEPTH) return false;
+	if (Array.isArray(node)) {
+		for (const item of node) if (schemaNeedsRepair(item, depth + 1, insideArrayItem)) return true;
+		return false;
+	}
+	if (!isRecord(node)) return false;
+	if (insideArrayItem && node.maxLength === LLAMA_CPP_BROKEN_NESTED_MAX_LENGTH) return true;
+	for (const key of REF_KEYWORDS) if (typeof node[key] === "string") return true;
+	for (const key of DEFS_KEYWORDS) if (isRecord(node[key])) return true;
+	for (const [key, value] of Object.entries(node)) {
+		const childInsideArrayItem = insideArrayItem || (key === "items" && node.type === "array");
+		if (schemaNeedsRepair(value, depth + 1, childInsideArrayItem)) return true;
+	}
+	return false;
+}
+
+// ---------------------------------------------------------------------------
+// JSON pointer helpers
+// ---------------------------------------------------------------------------
+
+function decodeToken(token: string): string {
+	return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+interface ParsedRef {
+	kind: "defs" | "pointer" | "external";
+	tokens: string[];
+}
+
+/** Split `$ref` into its kind and path tokens. Only same-document refs are resolvable. */
+export function parseRef(ref: string): ParsedRef {
+	if (!ref.startsWith("#") && !ref.startsWith("/")) return { kind: "external", tokens: [] };
+	if (ref.includes("://")) return { kind: "external", tokens: [] };
+	const fragment = (ref.startsWith("#") ? ref.slice(1) : ref).replace(/^\//, "");
+	if (fragment === "") return { kind: "pointer", tokens: [] };
+	const tokens = fragment.split("/").map(decodeToken);
+	if (tokens.length > 1 && (tokens[0] === "$defs" || tokens[0] === "definitions")) {
+		return { kind: "defs", tokens: tokens.slice(1) };
+	}
+	return { kind: "pointer", tokens };
+}
+
+function lookupPointer(root: unknown, tokens: string[]): unknown {
+	let cursor: unknown = root;
+	for (const token of tokens) {
+		if (Array.isArray(cursor)) {
+			const index = Number(token);
+			if (!Number.isInteger(index) || index < 0 || index >= cursor.length) return undefined;
+			cursor = cursor[index];
+		} else if (isRecord(cursor) && token in cursor) {
+			cursor = cursor[token];
+		} else {
+			return undefined;
+		}
+	}
+	return cursor;
+}
+
+function sanitizeName(raw: string): string {
+	return raw.replace(/[^A-Za-z0-9_]/g, "_");
+}
+
+/** Register `def` under a unique key; identical content reuses the existing key. */
+function claimKey(registry: Rec, preferred: string, def: unknown): string {
+	const base = sanitizeName(preferred) || `Def${Object.keys(registry).length + 1}`;
+	if (!(base in registry)) return base;
+	if (fingerprint(registry[base]) === fingerprint(def)) return base;
+	let key = `${base}_2`;
+	let n = 2;
+	while (key in registry && fingerprint(registry[key]) !== fingerprint(def)) {
+		key = `${base}_${++n}`;
+	}
+	return key;
+}
+
+/** Rewrite `#/$defs/X` / `#/definitions/X` refs according to a rename map. */
+function applyRenames(node: unknown, renames: Map<string, string>, depth = 0): unknown {
+	if (depth > MAX_DEPTH || renames.size === 0) return node;
+	if (Array.isArray(node)) return node.map((item) => applyRenames(item, renames, depth + 1));
+	if (!isRecord(node)) return node;
+	const next: Rec = {};
+	for (const [key, value] of Object.entries(node)) {
+		if (key === "$ref" && typeof value === "string") {
+			const parsed = parseRef(value);
+			if (parsed.kind === "defs" && parsed.tokens.length === 1) {
+				next[key] = `#/$defs/${renames.get(parsed.tokens[0]) ?? parsed.tokens[0]}`;
+				continue;
+			}
+			next[key] = value;
+			continue;
+		}
+		next[key] = applyRenames(value, renames, depth + 1);
+	}
+	return next;
+}
+
+// ---------------------------------------------------------------------------
+// Pass 1 — hoist every nested $defs / definitions to a root registry
+// ---------------------------------------------------------------------------
+
+function hoistDefs(node: unknown, registry: Rec, depth = 0): unknown {
+	if (depth > MAX_DEPTH) return node;
+	if (Array.isArray(node)) return node.map((item) => hoistDefs(item, registry, depth + 1));
+	if (!isRecord(node)) return node;
+
+	// Definitions declared on THIS node (the Pydantic-nesting artefact). They are
+	// invisible to a root-scoped resolver, so lift them and rename on collision.
+	const renames = new Map<string, string>();
+	const pending: Array<{ key: string; def: unknown }> = [];
+	for (const defsKey of DEFS_KEYWORDS) {
+		const defs = node[defsKey];
+		if (!isRecord(defs)) continue;
+		for (const [name, def] of Object.entries(defs)) {
+			const key = claimKey(registry, name, def);
+			renames.set(name, key);
+			pending.push({ key, def });
+		}
+	}
+
+	const out: Rec = {};
+	for (const [key, value] of Object.entries(node)) {
+		if (DEFS_KEYWORDS.includes(key)) continue;
+		out[key] = hoistDefs(applyRenames(value, renames), registry, depth + 1);
+	}
+
+	// Register after the subtree so nested defs inside them get claimed too.
+	for (const { key, def } of pending) {
+		if (!(key in registry)) {
+			registry[key] = hoistDefs(applyRenames(def, renames), registry, depth + 1);
+		}
+	}
+
+	return out;
+}
+
+// ---------------------------------------------------------------------------
+// Pass 2 — inline every $ref
+// ---------------------------------------------------------------------------
+
+interface InlineState {
+	dropped: string[];
+	cyclic: string[];
+}
+
+function resolveRefTarget(ref: string, registry: Rec, root: Rec): unknown {
+	const parsed = parseRef(ref);
+	if (parsed.kind === "external") return undefined;
+	if (parsed.kind === "defs") {
+		const head = lookupPointer(registry, parsed.tokens);
+		if (head !== undefined) return head;
+		return lookupPointer(root, parsed.tokens); // fall back to literal root path
+	}
+	return lookupPointer(root, parsed.tokens);
+}
+
+function inlineRefs(node: unknown, registry: Rec, root: Rec, stack: string[], state: InlineState, depth = 0): unknown {
+	if (depth > MAX_DEPTH) return {};
+	if (Array.isArray(node)) return node.map((item) => inlineRefs(item, registry, root, stack, state, depth + 1));
+	if (!isRecord(node)) return node;
+
+	const own: Rec = {};
+	for (const [key, value] of Object.entries(node)) {
+		if (key === "$ref" || DEFS_KEYWORDS.includes(key)) continue;
+		if (SCHEMA_KEYWORDS.has(key)) own[key] = inlineRefs(value, registry, root, stack, state, depth + 1);
+		else if (SCHEMA_ARRAY_KEYWORDS.has(key) && Array.isArray(value)) {
+			own[key] = value.map((item) => inlineRefs(item, registry, root, stack, state, depth + 1));
+		} else if (SCHEMA_MAP_KEYWORDS.has(key) && isRecord(value)) {
+			const bag: Rec = {};
+			for (const [pk, pv] of Object.entries(value)) bag[pk] = inlineRefs(pv, registry, root, stack, state, depth + 1);
+			own[key] = bag;
+		} else if (key === "required" && Array.isArray(value)) own[key] = [...value];
+		else own[key] = value;
+	}
+
+	const ref = node.$ref;
+	if (typeof ref !== "string") return own;
+
+	if (stack.includes(ref)) {
+		// Recursive schema — cannot inline infinitely. Accept anything at this node.
+		state.cyclic.push(ref);
+		return own;
+	}
+	const target = resolveRefTarget(ref, registry, root);
+	if (target === undefined) {
+		// Dangling pointer. llama.cpp fails the entire request on these.
+		state.dropped.push(ref);
+		return own;
+	}
+	const inlined = inlineRefs(target, registry, root, [...stack, ref], state, depth + 1);
+	// Target supplies structure; local siblings (description/title/examples) win.
+	return { ...(isRecord(inlined) ? inlined : {}), ...own };
+}
+
+/** Last line of defence: no `$ref` / `$defs` may survive onto the wire. */
+function stripRefArtifacts(node: unknown, depth = 0): unknown {
+	if (depth > MAX_DEPTH) return {};
+	if (Array.isArray(node)) return node.map((item) => stripRefArtifacts(item, depth + 1));
+	if (!isRecord(node)) return node;
+	const next: Rec = {};
+	for (const [key, value] of Object.entries(node)) {
+		if (key === "$ref" || DEFS_KEYWORDS.includes(key)) continue;
+		next[key] = stripRefArtifacts(value, depth + 1);
+	}
+	return next;
+}
+
+interface GrammarCompatibilityState {
+	adjustedLimits: number;
+}
+
+/**
+ * Work around llama.cpp b10612's exact nested-array maxLength=2000 parser bug.
+ * 1999, 2001, and much larger values work; 2001 is the least permissive safe wire
+ * value and the MCP tool still enforces its authoritative 2000-character limit.
+ */
+function normalizeGrammarCompatibility(
+	node: unknown,
+	state: GrammarCompatibilityState,
+	insideArrayItem = false,
+	depth = 0,
+): unknown {
+	if (depth > MAX_DEPTH) return {};
+	if (Array.isArray(node)) {
+		return node.map((item) => normalizeGrammarCompatibility(item, state, insideArrayItem, depth + 1));
+	}
+	if (!isRecord(node)) return node;
+	const next: Rec = {};
+	for (const [key, value] of Object.entries(node)) {
+		if (key === "maxLength" && insideArrayItem && value === LLAMA_CPP_BROKEN_NESTED_MAX_LENGTH) {
+			next[key] = LLAMA_CPP_SAFE_NESTED_MAX_LENGTH;
+			state.adjustedLimits++;
+			continue;
+		}
+		const childInsideArrayItem = insideArrayItem || (key === "items" && node.type === "array");
+		next[key] = normalizeGrammarCompatibility(value, state, childInsideArrayItem, depth + 1);
+	}
+	return next;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface SingleSchemaRepair {
+	schema: unknown;
+	repaired: boolean;
+	dropped: string[];
+	cyclic: string[];
+	adjustedGrammarLimits: number;
+}
+
+/** Repair one tool `parameters` schema. Returns the original identity when clean. */
+export function repairToolSchema(parameters: unknown): SingleSchemaRepair {
+	if (!isRecord(parameters) || !schemaNeedsRepair(parameters)) {
+		return { schema: parameters, repaired: false, dropped: [], cyclic: [], adjustedGrammarLimits: 0 };
+	}
+	const registry: Rec = {};
+	// Seed with the author's own root-level defs so root refs still resolve.
+	for (const defsKey of DEFS_KEYWORDS) {
+		const defs = parameters[defsKey];
+		if (isRecord(defs)) {
+			for (const [name, def] of Object.entries(defs)) {
+				const key = claimKey(registry, name, def);
+				registry[key] = def;
+			}
+		}
+	}
+	const hoisted = hoistDefs(parameters, registry);
+	const state: InlineState = { dropped: [], cyclic: [] };
+	const inlined = inlineRefs(hoisted, registry, parameters, [], state);
+	const cleaned = stripRefArtifacts(inlined);
+	const grammarState: GrammarCompatibilityState = { adjustedLimits: 0 };
+	const compatible = normalizeGrammarCompatibility(cleaned, grammarState);
+	return {
+		schema: compatible,
+		repaired: fingerprint(compatible) !== fingerprint(parameters),
+		dropped: [...new Set(state.dropped)],
+		cyclic: [...new Set(state.cyclic)],
+		adjustedGrammarLimits: grammarState.adjustedLimits,
+	};
+}
+
+/** Repair every tool schema in an outgoing chat/completions payload (identity if clean). */
+export function repairRequestToolSchemas(payload: unknown): { payload: unknown; report: ToolSchemaRepairReport } {
+	if (!isRecord(payload)) return { payload, report: EMPTY_REPORT };
+	const tools = payload.tools;
+	if (!Array.isArray(tools) || tools.length === 0) return { payload, report: EMPTY_REPORT };
+
+	const repairedTools: string[] = [];
+	const droppedRefs: string[] = [];
+	const cyclicRefs: string[] = [];
+	let adjustedGrammarLimits = 0;
+	let nextTools: unknown[] | undefined;
+
+	tools.forEach((tool, index) => {
+		if (!isRecord(tool)) return;
+		const fn = isRecord(tool.function) ? tool.function : undefined;
+		const holder: Rec | undefined = fn ?? tool;
+		const parameters = holder?.parameters;
+		if (!isRecord(parameters)) return;
+		const result = repairToolSchema(parameters);
+		if (!result.repaired) return;
+
+		repairedTools.push(String(fn?.name ?? tool.name ?? `tool[${index}]`));
+		droppedRefs.push(...result.dropped);
+		cyclicRefs.push(...result.cyclic);
+		adjustedGrammarLimits += result.adjustedGrammarLimits;
+		if (!nextTools) nextTools = [...tools];
+		nextTools[index] = fn
+			? { ...tool, function: { ...fn, parameters: result.schema } }
+			: { ...tool, parameters: result.schema };
+	});
+
+	if (!nextTools) return { payload, report: EMPTY_REPORT };
+	return {
+		payload: { ...payload, tools: nextTools },
+		report: {
+			repairedTools,
+			droppedRefs: [...new Set(droppedRefs)],
+			cyclicRefs: [...new Set(cyclicRefs)],
+			adjustedGrammarLimits,
+			changed: true,
+		},
+	};
+}
+
+/** One-line human summary for a log/status notice. */
+export function describeToolSchemaRepair(report: ToolSchemaRepairReport): string {
+	if (!report.changed) return "";
+	const shown = report.repairedTools.slice(0, NOTICE_LIMIT).join(", ");
+	const more = report.repairedTools.length > NOTICE_LIMIT ? ` +${report.repairedTools.length - NOTICE_LIMIT} more` : "";
+	const parts = [`repaired ${report.repairedTools.length} local tool schema(s): ${shown}${more}`];
+	if (report.adjustedGrammarLimits > 0) {
+		parts.push(`worked around nested maxLength=2000 grammar bug in ${report.adjustedGrammarLimits} location(s)`);
+	}
+	if (report.droppedRefs.length > 0) parts.push(`loosened unresolvable refs: ${report.droppedRefs.slice(0, NOTICE_LIMIT).join(", ")}`);
+	if (report.cyclicRefs.length > 0) parts.push(`loosened recursive refs: ${report.cyclicRefs.slice(0, NOTICE_LIMIT).join(", ")}`);
+	return parts.join("; ");
+}
+
+/** True for self-hosted endpoints on the local network (where grammar converters live). */
+export function isLocalEndpointUrl(baseUrl: string): boolean {
+	let host: string;
+	try {
+		host = new URL(baseUrl).hostname.toLowerCase().replace(/^\[|\]$/g, "");
+	} catch {
+		return false;
+	}
+	if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host === "::1" || host === "0.0.0.0") return true;
+	const octets = host.split(".").map(Number);
+	if (octets.length === 4 && octets.every((o) => Number.isInteger(o) && o >= 0 && o <= 255)) {
+		const [a, b] = octets as [number, number];
+		if (a === 127 || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168)) return true;
+	}
+	return false;
+}

package/scripts/bisect-grammar.ts

@@ -0,0 +1,65 @@
+/**
+ * Identify individual MCP tool schemas a llama.cpp endpoint cannot compile.
+ *   node --experimental-strip-types scripts/bisect-grammar.ts BASE_URL [MODEL] [TOOL_FILTER]
+ *
+ * The repair is applied first; a failure here therefore isolates an additional
+ * converter limitation rather than the known $defs/$ref issue.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { repairRequestToolSchemas } from "../schema-repair.ts";
+
+const BASE = process.argv[2];
+const MODEL = process.argv[3] ?? "qwen3.8-27b";
+const FILTER = process.argv[4];
+const CACHE = process.env.PI_MCP_CACHE ?? join(homedir(), ".pi", "agent", "mcp-cache.json");
+
+if (!BASE) {
+	console.error("usage: node --experimental-strip-types scripts/bisect-grammar.ts BASE_URL [MODEL] [TOOL_FILTER]");
+	process.exit(2);
+}
+
+const cache = JSON.parse(readFileSync(CACHE, "utf8")) as {
+	servers: Record<string, { tools?: Record<string, unknown>[] }>;
+};
+
+const tools: Record<string, unknown>[] = [];
+for (const [server, spec] of Object.entries(cache.servers)) {
+	for (const tool of spec.tools ?? []) {
+		const fn = (tool.function ?? tool) as Record<string, unknown>;
+		const parameters = fn.parameters ?? fn.inputSchema;
+		if (!fn.name || !parameters) continue;
+		tools.push({ type: "function", function: { name: `${server}__${String(fn.name).replace(/[^A-Za-z0-9_-]/g, "_")}`, description: String(fn.description ?? ""), parameters } });
+	}
+}
+
+const repaired = repairRequestToolSchemas({ model: MODEL, messages: [{ role: "user", content: "x" }], max_tokens: 8, tools }).payload as { tools: Record<string, unknown>[] };
+let candidates = repaired.tools;
+if (FILTER) candidates = candidates.filter((t) => String((t.function as Record<string, unknown>).name).includes(FILTER));
+
+async function post(subset: Record<string, unknown>[]): Promise<{ status: number; msg: string }> {
+	const res = await fetch(`${BASE}/v1/chat/completions`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ model: MODEL, messages: [{ role: "user", content: "reply OK" }], max_tokens: 8, tools: subset }),
+	});
+	const body = await res.text();
+	await new Promise((resolve) => setTimeout(resolve, 100));
+	return { status: res.status, msg: body.slice(0, 160) };
+}
+
+console.log(`probing ${candidates.length} tool(s) against ${BASE} (${MODEL})`);
+
+// 1. individual probe
+const failing: string[] = [];
+for (const tool of candidates) {
+	const name = String((tool.function as Record<string, unknown>).name);
+	const { status, msg } = await post([tool]);
+	if (status !== 200) {
+		failing.push(name);
+		console.log(`FAIL ${status} ${name}\n     ${msg}`);
+	}
+}
+console.log(`\nindividually failing: ${failing.length === 0 ? "none" : failing.join(", ")}`);
+process.exit(0);

package/scripts/live-schema-repair-check.ts

@@ -0,0 +1,86 @@
+/**
+ * LIVE verification: push the local Pi MCP catalogue through the repair and against
+ * a llama.cpp-compatible endpoint. Not part of `npm test` (needs the network).
+ *
+ *   node --experimental-strip-types scripts/live-schema-repair-check.ts BASE_URL [MODEL]
+ *
+ * This sends tool definitions but never executes a tool call.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { repairRequestToolSchemas, describeToolSchemaRepair } from "../schema-repair.ts";
+
+const BASE = process.argv[2];
+const MODEL = process.argv[3] ?? "qwen3.8-27b";
+const CACHE = process.env.PI_MCP_CACHE ?? join(homedir(), ".pi", "agent", "mcp-cache.json");
+
+if (!BASE) {
+	console.error("usage: node --experimental-strip-types scripts/live-schema-repair-check.ts BASE_URL [MODEL]");
+	process.exit(2);
+}
+
+function collectRefs(node: unknown, out: string[] = []): string[] {
+	if (Array.isArray(node)) for (const item of node) collectRefs(item, out);
+	else if (node && typeof node === "object") {
+		for (const [key, value] of Object.entries(node)) {
+			if (key === "$ref" && typeof value === "string") out.push(value);
+			else if (key === "$defs" || key === "definitions") out.push(`<${key}:${Object.keys(value as object).length} entries>`);
+			else collectRefs(value, out);
+		}
+	}
+	return out;
+}
+
+async function post(tools: unknown[], model = MODEL): Promise<{ status: number; body: string }> {
+	const res = await fetch(`${BASE}/v1/chat/completions`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ model, messages: [{ role: "user", content: "reply with OK" }], max_tokens: 16, tools }),
+	});
+	return { status: res.status, body: await res.text() };
+}
+
+if (!existsSync(CACHE)) {
+	console.error(`no mcp cache at ${CACHE}`);
+	process.exit(2);
+}
+
+const cache = JSON.parse(readFileSync(CACHE, "utf8")) as { servers: Record<string, { tools?: Record<string, unknown>[] }> };
+const servers = Object.entries(cache.servers);
+const tools: Record<string, unknown>[] = [];
+for (const [name, server] of servers) {
+	for (const tool of (server.tools ?? []) as Record<string, unknown>[]) {
+		// MCP catalogue entries carry `inputSchema`; OpenAI-shaped ones carry `function.parameters`.
+		const fn = (tool.function ?? tool) as Record<string, unknown>;
+		const parameters = fn.parameters ?? fn.inputSchema;
+		if (!fn.name || !parameters) continue;
+		tools.push({
+			type: "function",
+			function: { name: `${name}__${String(fn.name).replace(/[^A-Za-z0-9_-]/g, "_")}`, description: String(fn.description ?? ""), parameters },
+		});
+	}
+}
+
+const broken = tools.filter((t) => collectRefs((t as { function: { parameters: unknown } }).function.parameters).length > 0);
+console.log(`endpoint        : ${BASE}`);
+console.log(`tools collected : ${tools.length} from ${servers.length} MCP servers`);
+console.log(`tools w/ refs  : ${broken.length}`);
+for (const t of broken) console.log(`  - ${String((t as { function: { name: string } }).function.name)}`);
+
+const before = await post(tools);
+console.log(`\nBEFORE repair -> HTTP ${before.status}`);
+if (before.status !== 200) console.log(`  ${before.body.slice(0, 260)}`);
+
+const { payload, report } = repairRequestToolSchemas({ model: MODEL, messages: [{ role: "user", content: "reply with OK" }], max_tokens: 16, tools });
+console.log(`\nrepair summary  : ${describeToolSchemaRepair(report) || "(nothing to repair)"}`);
+if (report.droppedRefs.length) console.log(`  loosened refs : ${report.droppedRefs.join(", ")}`);
+
+const after = await post((payload as { tools: unknown[] }).tools);
+console.log(`\nAFTER repair  -> HTTP ${after.status}`);
+if (after.status === 200) console.log("  ✅ llama-swap/llama.cpp accepted the repaired tool set");
+else console.log(`  ❌ ${after.body.slice(0, 260)}`);
+
+const leftovers = collectRefs((payload as { tools: unknown[] }).tools).filter((r) => r.startsWith("#") || r.includes("entries"));
+console.log(`\nresidual refs/defs on the wire: ${leftovers.length === 0 ? "none ✅" : leftovers.join(", ")}`);
+process.exit(after.status === 200 && leftovers.length === 0 ? 0 : 1);