@vib-rato/ai 0.16.0

package/src/utils/schema/root-combinator.d.ts

@@ -0,0 +1,12 @@
+/** True when a JSON Schema node describes an object (explicit `type` or `properties`). */
+export declare function isJsonSchemaObjectNode(schema: Record<string, unknown>): boolean;
+/**
+ * Flatten a provider-emitted tool ROOT whose top level is a `oneOf`/`anyOf`/`allOf`
+ * combinator into one `type: "object"` schema: merge object-branch properties,
+ * derive the discriminant (`action`) enum, keep the common required set, and demote
+ * leftover combinators plus per-branch guidance into the description. Nested
+ * combinators (inside individual properties) are left untouched.
+ *
+ * Idempotent: a root that already lacks top-level combinators is returned unchanged.
+ */
+export declare function flattenToolRootCombinators(schema: Record<string, unknown>): Record<string, unknown>;

package/src/utils/schema/root-combinator.ts

@@ -0,0 +1,143 @@
+/**
+ * Tool `input_schema` root flattening.
+ *
+ * Tool/function-calling `input_schema` roots MUST be a single JSON Schema object.
+ * Bedrock Converse (`toolConfig.tools[*].toolSpec.inputSchema.json.type must be
+ * one of the following: object`), OpenAI strict mode, Gemini, and Anthropic all
+ * reject roots whose top level is a bare `oneOf`/`anyOf`/`allOf` combinator (the
+ * validators require `type: "object"`).
+ *
+ * Zod `z.union(...)` / `z.discriminatedUnion(...)` tool parameters serialize to
+ * exactly such a combinator root, so this normalization is provider-agnostic and
+ * runs inside the shared wire pipeline (`toolWireSchema`).
+ */
+import { isRecord } from "@vib-rato/utils";
+import { COMBINATOR_KEYS } from "./fields";
+import { spillToDescription } from "./spill";
+
+/** `minItems` / `maxItems` apply to arrays; some validators reject them on `type: "object"`. */
+function isJsonSchemaArrayNode(schema: Record<string, unknown>): boolean {
+	const t = schema.type;
+	if (t === "array") return true;
+	if (Array.isArray(t) && t.includes("array") && !t.includes("object")) return true;
+	return false;
+}
+
+/** True when a JSON Schema node describes an object (explicit `type` or `properties`). */
+export function isJsonSchemaObjectNode(schema: Record<string, unknown>): boolean {
+	if (isJsonSchemaArrayNode(schema)) return false;
+	if (schema.type === "object") return true;
+	if (Array.isArray(schema.type) && schema.type.includes("object")) return true;
+	if (isRecord(schema.properties)) return true;
+	return false;
+}
+
+function getRequiredNames(schema: Record<string, unknown>): Set<string> {
+	return new Set(
+		Array.isArray(schema.required)
+			? schema.required.filter((entry): entry is string => typeof entry === "string")
+			: [],
+	);
+}
+
+function getSingleLiteralValue(schema: unknown): unknown | undefined {
+	if (!isRecord(schema)) return undefined;
+	if (Object.hasOwn(schema, "const")) return schema.const;
+	if (Array.isArray(schema.enum) && schema.enum.length === 1) return schema.enum[0];
+	return undefined;
+}
+
+function describeRootBranch(index: number, branch: Record<string, unknown>, action: unknown): string {
+	const required = [...getRequiredNames(branch)];
+	const parts = [`Branch ${index + 1}`];
+	if (typeof action === "string" || typeof action === "number" || typeof action === "boolean") {
+		parts.push(`action ${JSON.stringify(action)}`);
+	}
+	if (required.length > 0) parts.push(`branch-required fields: ${required.join(", ")}`);
+	if (typeof branch.description === "string" && branch.description.length > 0) parts.push(branch.description);
+	return parts.join("; ");
+}
+
+function collectRootObjectBranches(schema: unknown): Record<string, unknown>[] | undefined {
+	if (!isRecord(schema)) return undefined;
+	if (isJsonSchemaObjectNode(schema)) return [schema];
+
+	const combinatorKeys = COMBINATOR_KEYS.filter(key => Array.isArray(schema[key]));
+	if (combinatorKeys.length === 0) return undefined;
+
+	const branches: Record<string, unknown>[] = [];
+	for (const key of combinatorKeys) {
+		const variants = schema[key];
+		if (!Array.isArray(variants) || variants.length === 0) return undefined;
+		for (const variant of variants) {
+			const nestedBranches = collectRootObjectBranches(variant);
+			if (nestedBranches === undefined) return undefined;
+			branches.push(...nestedBranches);
+		}
+	}
+	return branches;
+}
+
+/**
+ * Flatten a provider-emitted tool ROOT whose top level is a `oneOf`/`anyOf`/`allOf`
+ * combinator into one `type: "object"` schema: merge object-branch properties,
+ * derive the discriminant (`action`) enum, keep the common required set, and demote
+ * leftover combinators plus per-branch guidance into the description. Nested
+ * combinators (inside individual properties) are left untouched.
+ *
+ * Idempotent: a root that already lacks top-level combinators is returned unchanged.
+ */
+export function flattenToolRootCombinators(schema: Record<string, unknown>): Record<string, unknown> {
+	const rootCombinators = COMBINATOR_KEYS.filter(key => Array.isArray(schema[key]));
+	if (rootCombinators.length === 0) return schema;
+	const result: Record<string, unknown> = { ...schema };
+
+	const baseProperties = isRecord(result.properties) ? { ...result.properties } : {};
+	const flattenedBranches = rootCombinators
+		.map(key => ({ key, branches: collectRootObjectBranches({ [key]: result[key] }) }))
+		.find(entry => entry.branches !== undefined && entry.branches.length > 0);
+
+	result.type = "object";
+	result.properties = baseProperties;
+	result.additionalProperties = result.additionalProperties === undefined ? false : result.additionalProperties;
+
+	if (flattenedBranches?.branches !== undefined) {
+		const variants = flattenedBranches.branches;
+		const commonRequired = variants.map(variant => getRequiredNames(variant));
+		const required = [...commonRequired[0]].filter(name => commonRequired.every(set => set.has(name)));
+		const actionValues: unknown[] = [];
+		const guidance: string[] = [];
+
+		for (const [index, branch] of variants.entries()) {
+			if (isRecord(branch.properties)) {
+				Object.assign(baseProperties, branch.properties);
+				const actionValue = getSingleLiteralValue(branch.properties.action);
+				if (actionValue !== undefined && !actionValues.includes(actionValue)) actionValues.push(actionValue);
+				guidance.push(describeRootBranch(index, branch, actionValue));
+			} else {
+				guidance.push(describeRootBranch(index, branch, undefined));
+			}
+		}
+
+		if (actionValues.length > 0) {
+			const existingAction = isRecord(baseProperties.action) ? { ...baseProperties.action } : {};
+			delete existingAction.const;
+			baseProperties.action = { ...existingAction, enum: actionValues };
+		}
+		result.required = required;
+		spillToDescription(result, [
+			["rootCombinatorGuidance", guidance],
+			...rootCombinators
+				.filter(key => key !== flattenedBranches.key)
+				.map(key => [key, result[key]] as [string, unknown]),
+		]);
+	} else {
+		spillToDescription(
+			result,
+			rootCombinators.map(key => [key, result[key]]),
+		);
+	}
+
+	for (const key of COMBINATOR_KEYS) delete result[key];
+	return result;
+}

package/src/utils/schema/spill.d.ts

@@ -0,0 +1,8 @@
+import type { JsonObject } from "./types";
+export type DescriptionSpillFormat = "spill" | "paren";
+/**
+ * Demote stripped JSON Schema keywords into a node's `description` so the model
+ * still receives the constraint as natural-language context after the wire
+ * schema drops it.
+ */
+export declare function spillToDescription(node: JsonObject, entries: ReadonlyArray<readonly [string, unknown]>, format?: DescriptionSpillFormat): void;

package/src/utils/schema/spill.ts

@@ -0,0 +1,43 @@
+import type { JsonObject } from "./types";
+
+export type DescriptionSpillFormat = "spill" | "paren";
+
+function formatSpillValue(value: unknown): string {
+	return JSON.stringify(value);
+}
+
+function formatParenValue(value: unknown): string {
+	return typeof value === "string" ? value : JSON.stringify(value);
+}
+
+/**
+ * Demote stripped JSON Schema keywords into a node's `description` so the model
+ * still receives the constraint as natural-language context after the wire
+ * schema drops it.
+ */
+export function spillToDescription(
+	node: JsonObject,
+	entries: ReadonlyArray<readonly [string, unknown]>,
+	format: DescriptionSpillFormat = "spill",
+): void {
+	let spilled: Array<readonly [string, unknown]> | undefined;
+	for (const entry of entries) {
+		if (entry[1] === undefined) continue;
+		if (spilled === undefined) spilled = [];
+		spilled.push(entry);
+	}
+	if (spilled === undefined || spilled.length === 0) return;
+
+	const existing = typeof node.description === "string" ? node.description : "";
+	if (format === "paren") {
+		let suffix = "";
+		for (const [key, value] of spilled) {
+			suffix += ` (${key}: ${formatParenValue(value)})`;
+		}
+		node.description = `${existing}${suffix}`;
+		return;
+	}
+
+	const formatted = `{${spilled.map(([key, value]) => `${key}: ${formatSpillValue(value)}`).join(", ")}}`;
+	node.description = existing ? `${existing}\n\n${formatted}` : formatted;
+}

package/src/utils/schema/stamps.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Symbol-keyed lazy memoization stamped directly onto the host object.
+ *
+ * Faster than a module-level `WeakMap` in V8/JSC because the symbol slot is
+ * resolved through the object's hidden class instead of a side-table hash
+ * lookup. The slot is defined as a non-enumerable property so the stamp
+ * does not leak through `{...spread}`, `Object.keys`, `JSON.stringify`, or
+ * `toEqual`-style deep equality.
+ *
+ * Caveats: the stamp lives as long as the host object, even after callers
+ * release their references to the cached value — only use this for caches
+ * whose lifetime should match the host. Frozen hosts will throw on write in
+ * strict mode; callers that may receive frozen input must handle that.
+ */
+export declare function stamp<T extends object, V>(target: T, key: symbol, compute: (target: T) => V): V;
+export declare function epochNext(): number;
+/**
+ * Marks `target` as visited for this `epoch`. Returns `true` the first time
+ * it is called for a given (target, epoch) pair and `false` on every
+ * subsequent call within the same epoch.
+ */
+export declare function once<T extends object>(target: T, epoch: number): boolean;
+/** Returns `true` on first entry, `false` if `target` is already on the current path. */
+export declare function enter<T extends object>(target: T): boolean;
+export declare function exit<T extends object>(target: T): void;

package/src/utils/schema/stamps.ts

@@ -0,0 +1,97 @@
+/**
+ * Symbol-keyed lazy memoization stamped directly onto the host object.
+ *
+ * Faster than a module-level `WeakMap` in V8/JSC because the symbol slot is
+ * resolved through the object's hidden class instead of a side-table hash
+ * lookup. The slot is defined as a non-enumerable property so the stamp
+ * does not leak through `{...spread}`, `Object.keys`, `JSON.stringify`, or
+ * `toEqual`-style deep equality.
+ *
+ * Caveats: the stamp lives as long as the host object, even after callers
+ * release their references to the cached value — only use this for caches
+ * whose lifetime should match the host. Frozen hosts will throw on write in
+ * strict mode; callers that may receive frozen input must handle that.
+ */
+
+function define<T extends object>(target: T, key: symbol, value: unknown): void {
+	Object.defineProperty(target, key, { value, writable: true, configurable: true });
+}
+
+export function stamp<T extends object, V>(target: T, key: symbol, compute: (target: T) => V): V {
+	const slot = target as Record<symbol, V | undefined>;
+	const existing = slot[key];
+	if (existing !== undefined) return existing;
+	const value = compute(target);
+	define(target, key, value);
+	return value;
+}
+
+/**
+ * Epoch-keyed cycle guard. Cheaper than `WeakSet` for recursive traversal
+ * because the marker is a single property slot on the host object, written
+ * once and overwritten in place on every subsequent traversal — the hidden
+ * class transitions once per object lifetime, not per traversal.
+ *
+ * Usage:
+ *   function walk(node, epoch = epochNext()) {
+ *     if (!once(node, epoch)) return; // cycle
+ *     for (const child of node.children) walk(child, epoch);
+ *   }
+ */
+const kEpoch = Symbol("pi.schema.epoch");
+let __epoch = 0;
+
+export function epochNext(): number {
+	return ++__epoch;
+}
+
+/**
+ * Marks `target` as visited for this `epoch`. Returns `true` the first time
+ * it is called for a given (target, epoch) pair and `false` on every
+ * subsequent call within the same epoch.
+ */
+export function once<T extends object>(target: T, epoch: number): boolean {
+	const slot = target as Record<symbol, number | undefined>;
+	const cur = slot[kEpoch];
+	if (cur !== undefined && cur >= epoch) return false;
+	if (cur === undefined) define(target, kEpoch, epoch);
+	else slot[kEpoch] = epoch;
+	return true;
+}
+
+/**
+ * Counter-based path tracker. Use when a traversal needs to distinguish
+ * "currently on the recursion path" from "previously visited" — i.e. cycle
+ * detection that throws while still allowing DAG sharing. Increment on
+ * entry, decrement on exit; the slot returns to 0 after a balanced walk so
+ * subsequent top-level calls see a fresh state without any reset.
+ *
+ * Unlike a `WeakSet` with `seen.delete(...)`, the property is never deleted
+ * — only incremented and decremented — so the host object's hidden class
+ * is never invalidated.
+ *
+ * Usage:
+ *   function walk(node) {
+ *     if (!enter(node)) throw new Error("cycle");
+ *     try { for (const c of node.children) walk(c); }
+ *     finally { exit(node); }
+ *   }
+ */
+const kDepth = Symbol("pi.schema.depth");
+
+/** Returns `true` on first entry, `false` if `target` is already on the current path. */
+export function enter<T extends object>(target: T): boolean {
+	const slot = target as Record<symbol, number | undefined>;
+	const cur = slot[kDepth];
+	if (cur === undefined) {
+		define(target, kDepth, 1);
+		return true;
+	}
+	slot[kDepth] = cur + 1;
+	return cur === 0;
+}
+
+export function exit<T extends object>(target: T): void {
+	const slot = target as Record<symbol, number>;
+	slot[kDepth]--;
+}

package/src/utils/schema/types.d.ts

@@ -0,0 +1,4 @@
+export type JsonObject = Record<string, unknown>;
+export declare function isJsonObject(value: unknown): value is JsonObject;
+/** True when `value` is a plain JSON object with no own enumerable keys. */
+export declare function isJsonObjectEmpty(value: JsonObject): boolean;

package/src/utils/schema/types.ts

@@ -0,0 +1,11 @@
+export type JsonObject = Record<string, unknown>;
+
+export function isJsonObject(value: unknown): value is JsonObject {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** True when `value` is a plain JSON object with no own enumerable keys. */
+export function isJsonObjectEmpty(value: JsonObject): boolean {
+	for (const _ in value) return false;
+	return true;
+}

package/src/utils/schema/wire.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Compute the wire (JSON Schema) representation of a tool's parameters and
+ * convert TypeBox-style schemas into Zod for internal validation.
+ *
+ * Tools may author parameters in two shapes:
+ *   1. Zod (canonical going forward) — converted to JSON Schema on demand.
+ *   2. TypeBox / plain JSON Schema (legacy + extension compat) — upgraded to
+ *      draft 2020-12 without converting through Zod.
+ *
+ * Both are normalized at the boundary so providers and validators see the same
+ * JSON Schema dialect.
+ */
+import { type ZodType } from "zod/v4";
+import type { Tool } from "../../types";
+/**
+ * True when `value` is a live Zod schema instance.
+ *
+ * The check is stricter than "has a `_zod` property" because a JSON
+ * round-trip preserves the `_zod` key as a plain object and would otherwise
+ * fool the predicate — see issue #1101, where MCP servers ship
+ * `JSON.stringify(zodSchemaInstance)` as a tool's `inputSchema` and the
+ * resulting plain object then explodes `z.toJSONSchema` because the prototype
+ * (and every Zod parsing method) is gone.
+ *
+ * Live Zod instances always carry a `.parse` function on the prototype;
+ * impostors do not.
+ */
+export declare function isZodSchema(value: unknown): value is ZodType;
+/**
+ * Normalize `{}` (empty JSON Schema = `z.unknown()` / unconstrained value) to
+ * boolean `true` in every schema-valued position. JSON Schema draft 2020-12
+ * §4.3.1: `{}` and `true` are semantically equivalent ("any JSON value").
+ * Grammar-constrained samplers (llama.cpp, etc.) treat the object form as
+ * "generate an empty object" rather than "any JSON value", causing open-typed
+ * fields like `extra.title` (from `z.record(z.string(), z.unknown())`) to
+ * always emit `{}` instead of the intended string/number/etc. (issue #1179).
+ *
+ * Mutates in place. Provider-agnostic — applied to every tool wire schema so
+ * Anthropic, Google, OpenAI, Ollama, Bedrock, and Cursor all see the
+ * normalized form, regardless of whether the source was Zod or TypeBox.
+ */
+export declare function normalizeEmptySchemas(node: unknown): void;
+/** Convert a Zod schema into the JSON Schema shape providers consume. */
+export declare function zodToWireSchema(schema: ZodType): Record<string, unknown>;
+/**
+ * Resolve a tool's parameters to a JSON Schema object suitable for sending
+ * over the wire. Zod schemas are converted (and cached); legacy TypeBox / raw
+ * JSON Schema parameters are upgraded to draft 2020-12 (and cached).
+ *
+ * Both branches finish with `normalizeEmptySchemas` so every provider —
+ * OpenAI, Anthropic, Google, Ollama, Bedrock, Cursor — sees `{}` normalized
+ * to `true` in schema-valued positions (issue #1179).
+ */
+export declare function toolWireSchema(tool: Tool): Record<string, unknown>;

package/src/utils/schema/wire.ts

@@ -0,0 +1,213 @@
+/**
+ * Compute the wire (JSON Schema) representation of a tool's parameters and
+ * convert TypeBox-style schemas into Zod for internal validation.
+ *
+ * Tools may author parameters in two shapes:
+ *   1. Zod (canonical going forward) — converted to JSON Schema on demand.
+ *   2. TypeBox / plain JSON Schema (legacy + extension compat) — upgraded to
+ *      draft 2020-12 without converting through Zod.
+ *
+ * Both are normalized at the boundary so providers and validators see the same
+ * JSON Schema dialect.
+ */
+
+// We import the Zod *value* (z) for runtime APIs. Marker checks rely on the
+// `_zod` symbol that every Zod v4 schema instance carries.
+import { type ZodType, z } from "zod/v4";
+import type { Tool, TSchema } from "../../types";
+import { upgradeJsonSchemaTo202012 } from "./draft";
+import { stamp } from "./stamps";
+
+/**
+ * True when `value` is a live Zod schema instance.
+ *
+ * The check is stricter than "has a `_zod` property" because a JSON
+ * round-trip preserves the `_zod` key as a plain object and would otherwise
+ * fool the predicate — see issue #1101, where MCP servers ship
+ * `JSON.stringify(zodSchemaInstance)` as a tool's `inputSchema` and the
+ * resulting plain object then explodes `z.toJSONSchema` because the prototype
+ * (and every Zod parsing method) is gone.
+ *
+ * Live Zod instances always carry a `.parse` function on the prototype;
+ * impostors do not.
+ */
+export function isZodSchema(value: unknown): value is ZodType {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		// Zod v4 instances expose a `_zod` internal property with a `def` object.
+		// Tagging on this marker keeps the check stable across Zod minor versions.
+		// (`_zod` is part of Zod's documented internal contract used by introspection.)
+		// We avoid checking constructor name because Zod ships multiple variants
+		// (`ZodObject`, `ZodOptional`, etc.) and a tagged-union style check would
+		// have to enumerate them all.
+		"_zod" in value &&
+		typeof (value as { _zod?: { def?: unknown } })._zod === "object" &&
+		// Reject JSON-roundtripped objects that kept the `_zod` key but lost the
+		// prototype. Real instances have `.parse` on the prototype chain.
+		typeof (value as { parse?: unknown }).parse === "function"
+	);
+}
+
+/** Symbol-stamped caches keyed by schema object identity. */
+const kZodWireSchema = Symbol("pi.schema.zod.wire");
+const kJsonWireSchema = Symbol("pi.schema.json.wire");
+
+/**
+ * Post-process Zod-emitted JSON Schema so it matches the wire shape providers
+ * already expect from TypeBox-authored tools:
+ *
+ *   - Drop the `$schema` URL (providers parse the body, not the metadata).
+ *   - Make fields with a `default` non-required (TypeBox/JSON-Schema semantics
+ *     treat defaulted fields as optional; Zod inverts this and keeps them
+ *     required at the input boundary, then materializes the default).
+ *   - Strip the noisy safe-integer bounds Zod injects for `z.number().int()`.
+ *
+ * The empty-schema normalization (`{}` → `true`, see `normalizeEmptySchemas`)
+ * runs separately from `toolWireSchema` so both Zod and TypeBox tools get it.
+ */
+function postProcess(schema: Record<string, unknown>): Record<string, unknown> {
+	delete schema.$schema;
+	walk(schema);
+	normalizeEmptySchemas(schema);
+	return schema;
+}
+
+const SAFE_INTEGER_MAX = Number.MAX_SAFE_INTEGER;
+const SAFE_INTEGER_MIN = Number.MIN_SAFE_INTEGER;
+
+/** Keys whose values are a single JSON Schema (not an array or map). */
+const SCHEMA_VALUE_KEYS = [
+	"additionalProperties",
+	"unevaluatedProperties",
+	"unevaluatedItems",
+	"items",
+	"contains",
+	"propertyNames",
+	"if",
+	"then",
+	"else",
+	"not",
+] as const;
+
+/** Keys whose values are a map of `{ key: Schema }` entries. */
+const SCHEMA_MAP_KEYS = ["properties", "patternProperties", "$defs", "definitions"] as const;
+
+/** Keys whose values are an array of schemas. */
+const SCHEMA_ARRAY_KEYS = ["anyOf", "oneOf", "allOf", "prefixItems"] as const;
+
+/** True when `val` is a plain empty object `{}`. */
+function isEmptyObject(val: unknown): val is Record<string, never> {
+	if (val === null || typeof val !== "object" || Array.isArray(val)) return false;
+	for (const _ in val as object) return false;
+	return true;
+}
+
+function walk(node: unknown): void {
+	if (Array.isArray(node)) {
+		for (const child of node) walk(child);
+		return;
+	}
+	if (!node || typeof node !== "object") return;
+	const obj = node as Record<string, unknown>;
+
+	// Drop noise injected for `z.number().int()`.
+	if (obj.type === "integer") {
+		if (obj.minimum === SAFE_INTEGER_MIN) delete obj.minimum;
+		if (obj.maximum === SAFE_INTEGER_MAX) delete obj.maximum;
+	}
+
+	// Make defaulted properties non-required.
+	if (Array.isArray(obj.required) && obj.properties && typeof obj.properties === "object") {
+		const properties = obj.properties as Record<string, unknown>;
+		const required = obj.required as string[];
+		const filtered = required.filter(name => {
+			const propertySchema = properties[name];
+			if (!propertySchema || typeof propertySchema !== "object") return true;
+			return !("default" in (propertySchema as Record<string, unknown>));
+		});
+		if (filtered.length !== required.length) {
+			if (filtered.length === 0) {
+				delete obj.required;
+			} else {
+				obj.required = filtered;
+			}
+		}
+	}
+
+	for (const k in obj) walk(obj[k]);
+}
+
+/**
+ * Normalize `{}` (empty JSON Schema = `z.unknown()` / unconstrained value) to
+ * boolean `true` in every schema-valued position. JSON Schema draft 2020-12
+ * §4.3.1: `{}` and `true` are semantically equivalent ("any JSON value").
+ * Grammar-constrained samplers (llama.cpp, etc.) treat the object form as
+ * "generate an empty object" rather than "any JSON value", causing open-typed
+ * fields like `extra.title` (from `z.record(z.string(), z.unknown())`) to
+ * always emit `{}` instead of the intended string/number/etc. (issue #1179).
+ *
+ * Mutates in place. Provider-agnostic — applied to every tool wire schema so
+ * Anthropic, Google, OpenAI, Ollama, Bedrock, and Cursor all see the
+ * normalized form, regardless of whether the source was Zod or TypeBox.
+ */
+export function normalizeEmptySchemas(node: unknown): void {
+	if (Array.isArray(node)) {
+		for (const child of node) normalizeEmptySchemas(child);
+		return;
+	}
+	if (!node || typeof node !== "object") return;
+	const obj = node as Record<string, unknown>;
+
+	for (const key of SCHEMA_VALUE_KEYS) {
+		if (Object.hasOwn(obj, key) && isEmptyObject(obj[key])) obj[key] = true;
+	}
+	for (const mapKey of SCHEMA_MAP_KEYS) {
+		const map = obj[mapKey];
+		if (map !== null && typeof map === "object" && !Array.isArray(map)) {
+			for (const k in map as Record<string, unknown>) {
+				if (isEmptyObject((map as Record<string, unknown>)[k])) (map as Record<string, unknown>)[k] = true;
+			}
+		}
+	}
+	for (const arrKey of SCHEMA_ARRAY_KEYS) {
+		const arr = obj[arrKey];
+		if (Array.isArray(arr)) {
+			for (let i = 0; i < arr.length; i++) {
+				if (isEmptyObject(arr[i])) arr[i] = true;
+			}
+		}
+	}
+
+	for (const k in obj) normalizeEmptySchemas(obj[k]);
+}
+
+/** Convert a Zod schema into the JSON Schema shape providers consume. */
+export function zodToWireSchema(schema: ZodType): Record<string, unknown> {
+	return stamp(schema, kZodWireSchema, s => {
+		// `target: "draft-2020-12"` matches what Anthropic's `input_schema` validator
+		// requires out of the box; our other provider sanitizers (OpenAI strict,
+		// Google, Anthropic CCA) already handle the superset structurally.
+		const raw = z.toJSONSchema(s, { target: "draft-2020-12" }) as Record<string, unknown>;
+		return postProcess(raw);
+	});
+}
+
+/**
+ * Resolve a tool's parameters to a JSON Schema object suitable for sending
+ * over the wire. Zod schemas are converted (and cached); legacy TypeBox / raw
+ * JSON Schema parameters are upgraded to draft 2020-12 (and cached).
+ *
+ * Both branches finish with `normalizeEmptySchemas` so every provider —
+ * OpenAI, Anthropic, Google, Ollama, Bedrock, Cursor — sees `{}` normalized
+ * to `true` in schema-valued positions (issue #1179).
+ */
+export function toolWireSchema(tool: Tool): Record<string, unknown> {
+	const params: TSchema = tool.parameters;
+	if (isZodSchema(params)) return zodToWireSchema(params);
+	return stamp(params as Record<string, unknown>, kJsonWireSchema, p => {
+		const upgraded = upgradeJsonSchemaTo202012(p) as Record<string, unknown>;
+		normalizeEmptySchemas(upgraded);
+		return upgraded;
+	});
+}

package/src/utils/schema/zod-decontaminate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Defensive rewrite for nodes that look like `JSON.stringify(zodSchemaInstance)`
+ * output rather than JSON Schema. MCP servers using Zod 4 sometimes ship a
+ * serialised schema instance directly as a tool's `inputSchema`, because the
+ * fields Zod surfaces on its instances (`type`, `enum`, `options`, `def`) shadow
+ * (and clash with) JSON Schema keywords. The resulting payload is neither valid
+ * Zod nor valid JSON Schema 2020-12 and Anthropic's strict validator rejects
+ * the whole tool list.
+ *
+ * Symptoms we've observed (gitnexus_impact.direction):
+ *   {
+ *     def:   { type: "enum", entries: { upstream: "upstream", ... } },
+ *     type:  "enum",                       // <- invalid `type` value
+ *     enum:  { upstream: "upstream", ... }, // <- `enum` MUST be an array
+ *     options: ["upstream", "downstream"],
+ *   }
+ *
+ * This module recognises the shape (`def.type === node.type` and `def.type` is
+ * a known Zod kind) and rewrites it to clean JSON Schema where deterministic.
+ * For Zod kinds we don't fully model, we strip the toxic siblings (`def`,
+ * `options`, object-shaped `enum`) and drop an invalid `type` so the remainder
+ * passes meta-schema validation as a permissive node.
+ *
+ * Pure / identity-preserving: returns the input reference when nothing changes.
+ */
+/**
+ * Walks a JSON value and rewrites every Zod-instance-shaped node into clean
+ * JSON Schema 2020-12. Identity-preserving when no rewrite fires. Tolerates
+ * self-referential graphs — a revisited node returns as-is.
+ */
+export declare function decontaminateZodInstance(value: unknown): unknown;