@f5-sales-demo/pi-ai 19.51.2

package/src/utils/schema/normalize-cca.ts

@@ -0,0 +1,479 @@
+import { logger } from "@f5xc-salesdemos/pi-utils";
+import type { AnySchema } from "ajv";
+import Ajv2020 from "ajv/dist/2020.js";
+import { areJsonValuesEqual, mergePropertySchemas } from "./equality";
+import { CLOUD_CODE_ASSIST_SHARED_SCHEMA_KEYS, CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS } from "./fields";
+import { sanitizeSchemaForCCA } from "./sanitize-google";
+import type { JsonObject } from "./types";
+import { isJsonObject } from "./types";
+
+/** Copy all keys from a schema except the specified combiner key. */
+export function copySchemaWithout(schema: JsonObject, combiner: string): JsonObject {
+	const { [combiner]: _, ...rest } = schema;
+	return rest;
+}
+
+/**
+ * Claude via Cloud Code Assist (`parameters` path) can reject schemas that keep
+ * object variant combiners, so flatten object-only unions into one object shape.
+ */
+function mergeObjectCombinerVariants(schema: JsonObject, combiner: "anyOf" | "oneOf"): JsonObject {
+	const variantsRaw = schema[combiner];
+	if (!Array.isArray(variantsRaw) || variantsRaw.length === 0) {
+		return schema;
+	}
+
+	const variants: JsonObject[] = [];
+	for (const entry of variantsRaw) {
+		if (!isJsonObject(entry)) {
+			return schema;
+		}
+		const variantType = entry.type;
+		const hasObjectShape =
+			isJsonObject(entry.properties) ||
+			Array.isArray(entry.required) ||
+			Object.hasOwn(entry, "additionalProperties");
+		if (variantType === undefined && !hasObjectShape) {
+			return schema;
+		}
+		if (variantType !== undefined && variantType !== "object") {
+			return schema;
+		}
+		if (entry.properties !== undefined && !isJsonObject(entry.properties)) {
+			return schema;
+		}
+		if (entry.required !== undefined && !Array.isArray(entry.required)) {
+			return schema;
+		}
+		variants.push(entry);
+	}
+
+	const mergedProperties: JsonObject = {};
+	const ownProperties = isJsonObject(schema.properties) ? schema.properties : {};
+	for (const [name, propertySchema] of Object.entries(ownProperties)) {
+		mergedProperties[name] = propertySchema;
+	}
+
+	for (const variant of variants) {
+		const properties = isJsonObject(variant.properties) ? variant.properties : {};
+		for (const [name, propertySchema] of Object.entries(properties)) {
+			const existingSchema = mergedProperties[name];
+			mergedProperties[name] =
+				existingSchema === undefined ? propertySchema : mergePropertySchemas(existingSchema, propertySchema);
+		}
+	}
+
+	const nextSchema = copySchemaWithout(schema, combiner);
+
+	nextSchema.type = "object";
+	nextSchema.properties = mergedProperties;
+
+	// Compute intersection of all variants' required arrays
+	let requiredIntersection: string[] | undefined;
+	for (const variant of variants) {
+		const variantRequired = Array.isArray(variant.required)
+			? variant.required.filter((r): r is string => typeof r === "string")
+			: [];
+		if (requiredIntersection === undefined) {
+			requiredIntersection = [...variantRequired];
+		} else {
+			const reqSet = new Set(variantRequired);
+			requiredIntersection = requiredIntersection.filter(r => reqSet.has(r));
+		}
+	}
+	const parentRequired = Array.isArray(schema.required)
+		? schema.required.filter((r): r is string => typeof r === "string")
+		: [];
+	const ownPropertyNames = new Set(Object.keys(ownProperties));
+	const safeRequired = new Set<string>();
+	for (const name of requiredIntersection ?? []) {
+		if (name in mergedProperties) safeRequired.add(name);
+	}
+	for (const name of parentRequired) {
+		if (ownPropertyNames.has(name) && name in mergedProperties) {
+			safeRequired.add(name);
+		}
+	}
+	const requiredInPropertyOrder = Object.keys(mergedProperties).filter(name => safeRequired.has(name));
+	if (requiredInPropertyOrder.length > 0) {
+		nextSchema.required = requiredInPropertyOrder;
+	} else {
+		delete nextSchema.required;
+	}
+
+	return nextSchema;
+}
+
+/**
+ * Collapse anyOf/oneOf with distinct typed variants into a single-type schema.
+ * Picks the first non-null type as a scalar. This is lossy for multi-type unions
+ * (e.g., string|number|null narrows to string), but CCA requires a scalar type field
+ * and an uncollapsed anyOf would be rejected by the CCA API at runtime.
+ */
+function collapseMixedTypeCombinerVariants(schema: JsonObject, combiner: "anyOf" | "oneOf"): JsonObject {
+	const variantsRaw = schema[combiner];
+	if (!Array.isArray(variantsRaw) || variantsRaw.length === 0) {
+		return schema;
+	}
+
+	const seenTypes = new Set<string>();
+	const variantTypes: string[] = [];
+	const mergedVariantFields: JsonObject = {};
+	for (const entry of variantsRaw) {
+		if (!isJsonObject(entry) || typeof entry.type !== "string") {
+			return schema;
+		}
+
+		const variantType = entry.type;
+		if (seenTypes.has(variantType)) {
+			return schema;
+		}
+
+		const allowedKeys = CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS[variantType];
+		if (!allowedKeys) {
+			return schema;
+		}
+
+		for (const [key, variantValue] of Object.entries(entry)) {
+			if (key === "type") continue;
+			if (!allowedKeys.has(key) && !CLOUD_CODE_ASSIST_SHARED_SCHEMA_KEYS.has(key)) {
+				return schema;
+			}
+
+			const existingValue = mergedVariantFields[key];
+			if (existingValue !== undefined && !areJsonValuesEqual(existingValue, variantValue)) {
+				return schema;
+			}
+			mergedVariantFields[key] = variantValue;
+		}
+
+		seenTypes.add(variantType);
+		variantTypes.push(variantType);
+	}
+
+	if (variantTypes.length < 2 || variantTypes.every(type => type === "object")) {
+		return schema;
+	}
+
+	const nextSchema = copySchemaWithout(schema, combiner);
+
+	const nonNullTypes = variantTypes.filter(t => t !== "null");
+	// Lossy: when multiple non-null types exist we pick the first. CCA requires
+	// a scalar type and keeping the anyOf would cause an API rejection at runtime.
+	nextSchema.type = nonNullTypes[0] ?? variantTypes[0];
+	for (const [key, value] of Object.entries(mergedVariantFields)) {
+		const existingValue = nextSchema[key];
+		if (existingValue !== undefined && !areJsonValuesEqual(existingValue, value)) {
+			return schema;
+		}
+		if (existingValue === undefined) {
+			nextSchema[key] = value;
+		}
+	}
+	return nextSchema;
+}
+
+/**
+ * Collapse anyOf/oneOf where all variants share the same primitive type.
+ * E.g. anyOf: [{type: "string", desc: "A"}, {type: "string", desc: "B"}] -> {type: "string", desc: "A"}
+ * Claude via CCA rejects any remaining anyOf/oneOf, so pick first variant.
+ * Note: constraints from non-first variants are silently dropped.
+ */
+function collapseSameTypeCombinerVariants(schema: JsonObject, combiner: "anyOf" | "oneOf"): JsonObject {
+	const variantsRaw = schema[combiner];
+	if (!Array.isArray(variantsRaw) || variantsRaw.length === 0) return schema;
+	let commonType: string | undefined;
+	let firstEntry: JsonObject | undefined;
+	for (const entry of variantsRaw) {
+		if (!isJsonObject(entry) || typeof entry.type !== "string") return schema;
+		if (commonType === undefined) {
+			commonType = entry.type;
+			firstEntry = entry;
+		} else if (entry.type !== commonType) return schema;
+	}
+	if (!firstEntry) return schema;
+	const nextSchema = copySchemaWithout(schema, combiner);
+	for (const [key, value] of Object.entries(firstEntry)) {
+		if (!(key in nextSchema)) nextSchema[key] = value;
+	}
+	return nextSchema;
+}
+
+/**
+ * Recursively strip any remaining anyOf/oneOf that collapseSameTypeCombinerVariants can handle.
+ * This is needed because mergeObjectCombinerVariants can create new anyOf in merged
+ * properties AFTER the recursive normalization pass has already processed children.
+ */
+export function stripResidualCombiners(value: unknown, seen = new WeakSet<object>()): unknown {
+	if (Array.isArray(value)) {
+		if (seen.has(value)) return [];
+		seen.add(value);
+		return value.map(entry => stripResidualCombiners(entry, seen));
+	}
+	if (!isJsonObject(value)) return value;
+	if (seen.has(value)) return {};
+	seen.add(value);
+	const result: JsonObject = {};
+	for (const [key, entry] of Object.entries(value)) {
+		result[key] = stripResidualCombiners(entry, seen);
+	}
+	let current: JsonObject = result;
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const combiner of ["anyOf", "oneOf"] as const) {
+			const sameType = collapseSameTypeCombinerVariants(current, combiner);
+			if (sameType !== current) {
+				current = sameType;
+				changed = true;
+			}
+			const mixed = collapseMixedTypeCombinerVariants(current, combiner);
+			if (mixed !== current) {
+				current = mixed;
+				changed = true;
+			}
+		}
+	}
+	return current;
+}
+
+function normalizeSchemaForCCA(value: unknown, seen?: WeakSet<object>): unknown {
+	if (!seen) seen = new WeakSet();
+	if (Array.isArray(value)) {
+		if (seen.has(value)) return [];
+		seen.add(value);
+		return value.map(entry => normalizeSchemaForCCA(entry, seen));
+	}
+	if (!isJsonObject(value)) {
+		return value;
+	}
+	if (seen.has(value)) return {};
+	seen.add(value);
+
+	const normalized: JsonObject = {};
+	for (const [key, entry] of Object.entries(value)) {
+		normalized[key] = normalizeSchemaForCCA(entry, seen);
+	}
+
+	const mergedAnyOf = mergeObjectCombinerVariants(normalized, "anyOf");
+	const collapsedAnyOf = collapseMixedTypeCombinerVariants(mergedAnyOf, "anyOf");
+	const sameTypeAnyOf = collapseSameTypeCombinerVariants(collapsedAnyOf, "anyOf");
+	const mergedOneOf = mergeObjectCombinerVariants(sameTypeAnyOf, "oneOf");
+	const collapsedOneOf = collapseMixedTypeCombinerVariants(mergedOneOf, "oneOf");
+	return collapseSameTypeCombinerVariants(collapsedOneOf, "oneOf");
+}
+
+interface NullableExtractionResult {
+	schema: unknown;
+	nullable: boolean;
+}
+
+function extractNullableUnionSchema(schema: unknown): NullableExtractionResult {
+	if (!isJsonObject(schema)) {
+		return { schema, nullable: false };
+	}
+
+	if (schema.nullable === true) {
+		const nextSchema = { ...schema };
+		delete nextSchema.nullable;
+		return { schema: nextSchema, nullable: true };
+	}
+
+	if (Array.isArray(schema.type)) {
+		const typeVariants = schema.type.filter((entry): entry is string => typeof entry === "string");
+		const nonNullTypes = typeVariants.filter(entry => entry !== "null");
+		if (typeVariants.includes("null") && nonNullTypes.length === 1) {
+			const nextSchema = { ...schema, type: nonNullTypes[0] };
+			return { schema: nextSchema, nullable: true };
+		}
+	}
+
+	for (const combiner of ["anyOf", "oneOf"] as const) {
+		const variantsRaw = schema[combiner];
+		if (!Array.isArray(variantsRaw)) continue;
+
+		let hasNullVariant = false;
+		const nonNullVariants: unknown[] = [];
+		for (const variant of variantsRaw) {
+			if (isJsonObject(variant) && variant.type === "null" && Object.keys(variant).length === 1) {
+				hasNullVariant = true;
+				continue;
+			}
+			nonNullVariants.push(variant);
+		}
+
+		if (!hasNullVariant || nonNullVariants.length !== 1 || !isJsonObject(nonNullVariants[0])) {
+			continue;
+		}
+
+		const nextSchema = copySchemaWithout(schema, combiner);
+		for (const [key, value] of Object.entries(nonNullVariants[0])) {
+			const existingValue = nextSchema[key];
+			if (existingValue !== undefined && !areJsonValuesEqual(existingValue, value)) {
+				return { schema, nullable: false };
+			}
+			if (existingValue === undefined) {
+				nextSchema[key] = value;
+			}
+		}
+		return { schema: nextSchema, nullable: true };
+	}
+
+	return { schema, nullable: false };
+}
+
+interface NullableNormalizationResult {
+	schema: unknown;
+	nullable: boolean;
+}
+
+function normalizeNullablePropertiesForCloudCodeAssist(
+	value: unknown,
+	isPropertySchema = false,
+	seen?: WeakSet<object>,
+): NullableNormalizationResult {
+	if (!seen) seen = new WeakSet();
+	if (Array.isArray(value)) {
+		if (seen.has(value)) {
+			return { schema: [], nullable: false };
+		}
+		seen.add(value);
+		return {
+			schema: value.map(entry => normalizeNullablePropertiesForCloudCodeAssist(entry, false, seen).schema),
+			nullable: false,
+		};
+	}
+	if (!isJsonObject(value)) {
+		return { schema: value, nullable: false };
+	}
+	if (seen.has(value)) {
+		return { schema: {}, nullable: false };
+	}
+	seen.add(value);
+
+	const normalized: JsonObject = {};
+	for (const [key, entry] of Object.entries(value)) {
+		normalized[key] = normalizeNullablePropertiesForCloudCodeAssist(entry, false, seen).schema;
+	}
+
+	if (isJsonObject(normalized.properties)) {
+		const required = new Set(
+			Array.isArray(normalized.required)
+				? normalized.required.filter((entry): entry is string => typeof entry === "string")
+				: [],
+		);
+		const nextProperties: JsonObject = {};
+		for (const [name, propertySchema] of Object.entries(normalized.properties)) {
+			const normalizedProperty = normalizeNullablePropertiesForCloudCodeAssist(propertySchema, true, seen);
+			nextProperties[name] = normalizedProperty.schema;
+			if (normalizedProperty.nullable) {
+				required.delete(name);
+			}
+		}
+		normalized.properties = nextProperties;
+		if (Array.isArray(normalized.required)) {
+			normalized.required = Array.from(required);
+		}
+	}
+
+	if (!isPropertySchema) {
+		return { schema: normalized, nullable: false };
+	}
+
+	return extractNullableUnionSchema(normalized);
+}
+
+/**
+ * Lazy singleton AJV instance. Only used for validateSchema() — never compile().
+ * Do NOT use compile() on this instance: compiled schemas accumulate and leak memory.
+ * Note: Not thread-safe if Bun workers share this module.
+ */
+let cloudCodeAssistSchemaValidator: Ajv2020 | null = null;
+function getCloudCodeAssistSchemaValidator(): Ajv2020 {
+	if (cloudCodeAssistSchemaValidator) {
+		return cloudCodeAssistSchemaValidator;
+	}
+
+	cloudCodeAssistSchemaValidator = new Ajv2020({
+		allErrors: true,
+		strict: false,
+		validateSchema: true,
+	});
+	return cloudCodeAssistSchemaValidator;
+}
+
+/**
+ * Keep validation synchronous in this request path.
+ */
+function isValidCCASchema(schema: unknown): boolean {
+	try {
+		const result = getCloudCodeAssistSchemaValidator().validateSchema(schema as AnySchema);
+		return typeof result === "boolean" ? result : false;
+	} catch {
+		return false;
+	}
+}
+
+/** See COMBINATOR_KEYS in fields.ts — CCA forbids all three combiners. */
+const CCA_FORBIDDEN_COMBINERS = new Set(["anyOf", "oneOf", "allOf"] as const);
+
+function hasResidualCloudCodeAssistIncompatibilities(value: unknown, seen = new WeakSet<object>()): boolean {
+	if (Array.isArray(value)) {
+		if (seen.has(value)) return false;
+		seen.add(value);
+		return value.some(entry => hasResidualCloudCodeAssistIncompatibilities(entry, seen));
+	}
+	if (!isJsonObject(value)) {
+		return false;
+	}
+	if (seen.has(value)) {
+		return false;
+	}
+	seen.add(value);
+
+	if (Array.isArray(value.type) || value.type === "null") {
+		return true;
+	}
+	if (Object.hasOwn(value, "nullable")) {
+		return true;
+	}
+	for (const combiner of CCA_FORBIDDEN_COMBINERS) {
+		if (Array.isArray(value[combiner])) {
+			return true;
+		}
+	}
+	for (const entry of Object.values(value)) {
+		if (hasResidualCloudCodeAssistIncompatibilities(entry, seen)) {
+			return true;
+		}
+	}
+	return false;
+}
+const CLOUD_CODE_ASSIST_CLAUDE_FALLBACK_SCHEMA = {
+	type: "object",
+	properties: {},
+} as const;
+
+/**
+ * Prepare schema for Claude on Cloud Code Assist:
+ * sanitize -> normalize union objects -> validate -> fallback.
+ *
+ * Fallback is per-tool and fail-open to avoid rejecting the entire request when
+ * one tool schema is invalid.
+ */
+export function prepareSchemaForCCA(value: unknown): unknown {
+	const sanitized = sanitizeSchemaForCCA(value);
+	const pass1 = normalizeSchemaForCCA(sanitized);
+	// Second pass: strip anyOf/oneOf created by mergeObjectCombinerVariants during pass1
+	const normalized = stripResidualCombiners(pass1);
+	const nullableNormalized = normalizeNullablePropertiesForCloudCodeAssist(normalized).schema;
+	if (hasResidualCloudCodeAssistIncompatibilities(nullableNormalized)) {
+		logger.debug("CCA schema has residual incompatibilities, using fallback");
+		return CLOUD_CODE_ASSIST_CLAUDE_FALLBACK_SCHEMA;
+	}
+	if (isValidCCASchema(nullableNormalized)) {
+		return nullableNormalized;
+	}
+	logger.debug("CCA schema failed validation, using fallback");
+	return CLOUD_CODE_ASSIST_CLAUDE_FALLBACK_SCHEMA;
+}

package/src/utils/schema/sanitize-google.ts

@@ -0,0 +1,212 @@
+import { dereferenceJsonSchema } from "./dereference";
+import { areJsonValuesEqual } from "./equality";
+import { UNSUPPORTED_SCHEMA_FIELDS } from "./fields";
+
+interface SanitizeSchemaOptions {
+	insideProperties: boolean;
+	normalizeTypeArrayToNullable: boolean;
+	stripNullableKeyword: boolean;
+	unsupportedFields: ReadonlySet<string>;
+	seen: WeakSet<object>;
+}
+
+function inferJsonSchemaTypeFromValue(value: unknown): string | undefined {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	switch (typeof value) {
+		case "string":
+			return "string";
+		case "number":
+			return "number";
+		case "boolean":
+			return "boolean";
+		case "object":
+			return "object";
+		default:
+			return undefined;
+	}
+}
+
+function pushEnumValue(values: unknown[], value: unknown): void {
+	if (!values.some(existing => areJsonValuesEqual(existing, value))) {
+		values.push(value);
+	}
+}
+
+function sanitizeSchemaImpl(value: unknown, options: SanitizeSchemaOptions): unknown {
+	if (Array.isArray(value)) {
+		if (options.seen.has(value)) return [];
+		options.seen.add(value);
+		return value.map(entry => sanitizeSchemaImpl(entry, options));
+	}
+	if (!value || typeof value !== "object") {
+		return value;
+	}
+	if (options.seen.has(value as object)) return {};
+	options.seen.add(value as object);
+	const obj = value as Record<string, unknown>;
+	const result: Record<string, unknown> = {};
+	for (const combiner of ["anyOf", "oneOf"] as const) {
+		if (Array.isArray(obj[combiner])) {
+			const variants = obj[combiner] as Record<string, unknown>[];
+			const allHaveConst = variants.every(v => v && typeof v === "object" && "const" in v);
+			if (allHaveConst && variants.length > 0) {
+				const dedupedEnum: unknown[] = [];
+				for (const variant of variants) {
+					pushEnumValue(dedupedEnum, variant.const);
+				}
+				result.enum = dedupedEnum;
+
+				const explicitTypes = variants
+					.map(variant => variant.type)
+					.filter((variantType): variantType is string => typeof variantType === "string");
+				const allHaveSameExplicitType =
+					explicitTypes.length === variants.length &&
+					explicitTypes.every(variantType => variantType === explicitTypes[0]);
+				if (allHaveSameExplicitType && explicitTypes[0]) {
+					result.type = explicitTypes[0];
+				} else {
+					const inferredTypes = dedupedEnum
+						.map(enumValue => inferJsonSchemaTypeFromValue(enumValue))
+						.filter((inferredType): inferredType is string => inferredType !== undefined);
+					const inferredTypeSet = new Set(inferredTypes);
+					if (inferredTypeSet.size === 1) {
+						result.type = inferredTypes[0];
+					} else {
+						const nonNullInferredTypes = inferredTypes.filter(inferredType => inferredType !== "null");
+						const nonNullTypeSet = new Set(nonNullInferredTypes);
+						if (inferredTypes.includes("null") && nonNullTypeSet.size === 1) {
+							result.type = nonNullInferredTypes[0];
+							if (!options.stripNullableKeyword) {
+								result.nullable = true;
+							}
+						}
+					}
+				}
+
+				// Copy description and other top-level fields (not the combiner)
+				for (const [key, entry] of Object.entries(obj)) {
+					if (key !== combiner && !(key in result)) {
+						result[key] = sanitizeSchemaImpl(entry, {
+							...options,
+							insideProperties: key === "properties",
+						});
+					}
+				}
+				return result;
+			}
+		}
+	}
+	// Regular field processing
+	let constValue: unknown;
+	for (const [key, entry] of Object.entries(obj)) {
+		// Only strip unsupported schema keywords when NOT inside "properties" object
+		// Inside "properties", keys are property names (e.g., "pattern") not schema keywords
+		if (!options.insideProperties && options.unsupportedFields.has(key)) continue;
+		if (options.stripNullableKeyword && key === "nullable") continue;
+		if (key === "const") {
+			constValue = entry;
+			continue;
+		}
+		// When key is "properties", child keys are property names, not schema keywords
+		result[key] = sanitizeSchemaImpl(entry, {
+			...options,
+			insideProperties: key === "properties",
+		});
+	}
+	// Normalize array-valued "type" (e.g. ["string", "null"]) to a single type + nullable.
+	// Google's Schema proto expects type to be a single enum string, not an array.
+	if (options.normalizeTypeArrayToNullable && Array.isArray(result.type)) {
+		const types = (result.type as unknown[]).filter((t): t is string => typeof t === "string");
+		const nonNull = types.filter(t => t !== "null");
+		if (types.includes("null") && !options.stripNullableKeyword) {
+			result.nullable = true;
+		}
+		result.type = nonNull[0] ?? types[0];
+	}
+	if (constValue !== undefined) {
+		// Convert const to enum, merging with existing enum if present
+		const existingEnum = Array.isArray(result.enum) ? result.enum : [];
+		pushEnumValue(existingEnum, constValue);
+		result.enum = existingEnum;
+		if (!result.type) {
+			result.type = inferJsonSchemaTypeFromValue(constValue);
+		}
+	}
+
+	// Ensure object schemas have a properties field (some LLM providers require it)
+	if (result.type === "object" && !("properties" in result)) {
+		result.properties = {};
+	}
+
+	return result;
+}
+
+/**
+ * Sanitize a JSON Schema for Google's generative AI APIs by stripping unsupported
+ * JSON Schema keywords and normalizing representable nullable/type patterns.
+ *
+ * **Prerequisite:** The input schema must be fully dereferenced — all `$ref`
+ * pointers resolved inline — before calling this function. `$ref` is silently
+ * stripped as an unsupported keyword; unresolved references will produce an
+ * incomplete schema with no warning.
+ */
+export function sanitizeSchemaForGoogle(value: unknown): unknown {
+	return sanitizeSchemaImpl(value, {
+		insideProperties: false,
+		normalizeTypeArrayToNullable: true,
+		stripNullableKeyword: false,
+		unsupportedFields: UNSUPPORTED_SCHEMA_FIELDS,
+		seen: new WeakSet(),
+	});
+}
+
+/**
+ * Sanitize a JSON Schema for Cloud Code Assist Claude.
+ * Starts from Google sanitizer behavior, then strips `nullable` markers.
+ *
+ * **Prerequisite:** The input schema must be fully dereferenced — all `$ref`
+ * pointers resolved inline — before calling this function. `$ref` is silently
+ * stripped as an unsupported keyword; unresolved references will produce an
+ * incomplete schema with no warning.
+ */
+export function sanitizeSchemaForCCA(value: unknown): unknown {
+	return sanitizeSchemaImpl(value, {
+		insideProperties: false,
+		normalizeTypeArrayToNullable: true,
+		stripNullableKeyword: true,
+		unsupportedFields: UNSUPPORTED_SCHEMA_FIELDS,
+		seen: new WeakSet(),
+	});
+}
+
+/**
+ * Fields stripped for MCP/AJV compatibility.
+ * Only `$schema` — AJV throws on unrecognised meta-schema URIs
+ * (e.g. draft 2020-12 emitted by schemars 1.x / rmcp 0.15+).
+ */
+const MCP_UNSUPPORTED_SCHEMA_FIELDS = new Set(["$schema"]);
+
+/**
+ * Sanitize a JSON Schema for MCP tool parameter validation (AJV compatibility).
+ *
+ * Strips only the minimal set of fields that cause AJV validation errors:
+ * - `$schema`: AJV throws on unknown meta-schema URIs.
+ * - `nullable`: OpenAPI 3.0 extension, not standard JSON Schema.
+ *
+ * Unlike the Google/CCA sanitizers this preserves validation keywords
+ * (`pattern`, `format`, `additionalProperties`, etc.) and `$ref`/`$defs`.
+ */
+export function sanitizeSchemaForMCP(value: unknown): unknown {
+	// Dereference $ref/$defs first — MCP servers emit standard JSON Schema
+	// with $defs, but providers (Anthropic, Google) only forward `properties`
+	// and `required`, dropping $defs and leaving dangling $ref pointers.
+	const dereferenced = dereferenceJsonSchema(value);
+	return sanitizeSchemaImpl(dereferenced, {
+		insideProperties: false,
+		normalizeTypeArrayToNullable: false,
+		stripNullableKeyword: true,
+		unsupportedFields: MCP_UNSUPPORTED_SCHEMA_FIELDS,
+		seen: new WeakSet(),
+	});
+}