jeopi-ai 16.2.13

package/src/utils/schema/wire.ts

@@ -0,0 +1,789 @@
+/**
+ * Compute the wire (JSON Schema) representation of a tool's parameters.
+ *
+ * Tools may author parameters in three shapes:
+ *   1. Zod (canonical) — converted to JSON Schema on demand.
+ *   2. ArkType — converted to JSON Schema via its native `toJsonSchema`.
+ *   3. TypeBox / plain JSON Schema (legacy + extension compat) — upgraded to
+ *      draft 2020-12 without converting.
+ *
+ * All three are normalized at the boundary so providers and validators see the same
+ * JSON Schema dialect.
+ */
+
+import type { Type } from "arktype";
+// 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"
+	);
+}
+
+/**
+ * True when `value` is a live ArkType schema instance.
+ *
+ * ArkType schemas are callable functions carrying `toJsonSchema`/`assert`
+ * methods. Zod v4 instances are non-callable objects (keyed off `_zod`), and
+ * raw JSON Schema is a plain object — the three are disjoint. We deliberately
+ * avoid the Standard Schema `~standard` marker because Zod v4 implements it too.
+ */
+export function isArkSchema(value: unknown): value is Type {
+	return (
+		typeof value === "function" &&
+		typeof (value as { toJsonSchema?: unknown }).toJsonSchema === "function" &&
+		typeof (value as { assert?: unknown }).assert === "function"
+	);
+}
+
+function isArkJsonAst(value: unknown): boolean {
+	if (Array.isArray(value)) return value.some(isArkJsonAst);
+	if (!isSchemaRecord(value)) return false;
+	if (typeof value.domain === "string" || Object.hasOwn(value, "unit")) return true;
+	if (value.proto === "Array" && Object.hasOwn(value, "sequence")) return true;
+	const required = value.required;
+	return (
+		Array.isArray(required) &&
+		required.some(entry => isSchemaRecord(entry) && typeof entry.key === "string" && "value" in entry)
+	);
+}
+
+function parseArkObjectKey(key: string): { name: string; description?: string } {
+	const match = /^(.*?)\s*\/\*\*\s*([\s\S]*?)\s*\*\/\s*$/.exec(key);
+	if (!match) return { name: key };
+	return { name: match[1].trim(), description: match[2].trim() };
+}
+
+function withArkKeyDescription(schema: unknown, description: string | undefined): unknown {
+	if (!description) return schema;
+	if (isSchemaRecord(schema)) {
+		if (typeof schema.description !== "string") schema.description = description;
+		return schema;
+	}
+	return { anyOf: [schema], description };
+}
+
+function arkJsonAstToWire(value: unknown): unknown {
+	if (typeof value === "string") {
+		switch (value) {
+			case "string":
+			case "number":
+			case "integer":
+			case "boolean":
+			case "object":
+				return { type: value };
+			case "unknown":
+				return {};
+			default:
+				return {};
+		}
+	}
+
+	if (Array.isArray(value)) {
+		if (value.every(item => isSchemaRecord(item) && Object.hasOwn(item, "unit"))) {
+			return { enum: value.map(item => (item as { unit: unknown }).unit) };
+		}
+		return { anyOf: value.map(arkJsonAstToWire) };
+	}
+
+	if (!isSchemaRecord(value)) return {};
+
+	if (Object.hasOwn(value, "unit")) return { const: value.unit };
+
+	if (value.proto === "Array" && Object.hasOwn(value, "sequence")) {
+		return { type: "array", items: arkJsonAstToWire(value.sequence) };
+	}
+
+	if (value.domain === "object") {
+		const properties: Record<string, unknown> = {};
+		const required: string[] = [];
+		const addEntry = (entry: unknown, isRequired: boolean): void => {
+			if (!isSchemaRecord(entry) || typeof entry.key !== "string" || !("value" in entry)) return;
+			const key = parseArkObjectKey(entry.key);
+			properties[key.name] = withArkKeyDescription(arkJsonAstToWire(entry.value), key.description);
+			if (isRequired) required.push(key.name);
+		};
+		if (Array.isArray(value.required)) {
+			for (const entry of value.required) addEntry(entry, true);
+		}
+		if (Array.isArray(value.optional)) {
+			for (const entry of value.optional) addEntry(entry, false);
+		}
+		const schema: Record<string, unknown> = { type: "object", properties };
+		if (required.length > 0) schema.required = required;
+		return schema;
+	}
+
+	if (typeof value.domain === "string") return { type: value.domain };
+	return {};
+}
+
+/** Symbol-stamped caches keyed by schema object identity. */
+const kZodWireSchema = Symbol("pi.schema.zod.wire");
+const kJsonWireSchema = Symbol("pi.schema.json.wire");
+const kArkWireSchema = Symbol("pi.schema.ark.wire");
+const kStrippedSchema = Symbol("pi.schema.descriptions.stripped");
+
+/**
+ * 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, true);
+	normalizeArkPropertyComments(schema);
+	normalizeEmptySchemas(schema);
+	return schema;
+}
+
+function postProcessJsonSchema(schema: Record<string, unknown>): Record<string, unknown> {
+	walk(schema, false);
+	normalizeArkPropertyComments(schema);
+	normalizeEmptySchemas(schema);
+	return schema;
+}
+
+const SAFE_INTEGER_MAX = Number.MAX_SAFE_INTEGER;
+const SAFE_INTEGER_MIN = Number.MIN_SAFE_INTEGER;
+const NULLABLE_SCALAR_TYPES = new Set(["string", "number", "integer", "boolean"]);
+
+const SCHEMA_DEFINING_SIBLING_KEYS = new Set([
+	"$ref",
+	"additionalProperties",
+	"allOf",
+	"anyOf",
+	"const",
+	"contains",
+	"enum",
+	"if",
+	"items",
+	"not",
+	"oneOf",
+	"patternProperties",
+	"prefixItems",
+	"properties",
+	"propertyNames",
+	"then",
+	"else",
+	"unevaluatedItems",
+	"unevaluatedProperties",
+]);
+
+function isSchemaRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasSchemaDefiningSibling(schema: Record<string, unknown>): boolean {
+	for (const key in schema) {
+		if (key !== "anyOf" && SCHEMA_DEFINING_SIBLING_KEYS.has(key)) return true;
+	}
+	return false;
+}
+
+function isNullVariant(schema: Record<string, unknown>): boolean {
+	return schema.type === "null" && Object.keys(schema).length === 1;
+}
+
+function isScalarVariant(schema: Record<string, unknown>): schema is Record<string, unknown> & { type: string } {
+	return typeof schema.type === "string" && NULLABLE_SCALAR_TYPES.has(schema.type);
+}
+
+function hasIntegerType(type: unknown): boolean {
+	return type === "integer" || (Array.isArray(type) && type.includes("integer"));
+}
+
+function copyNullableScalarConstraints(schema: Record<string, unknown>, scalarVariant: Record<string, unknown>): void {
+	for (const key in scalarVariant) {
+		if (key === "type" || key === "enum" || key === "const" || Object.hasOwn(schema, key)) continue;
+		schema[key] = scalarVariant[key];
+	}
+
+	if (Object.hasOwn(scalarVariant, "const")) {
+		schema.enum = [scalarVariant.const, null];
+		return;
+	}
+
+	const enumValues = scalarVariant.enum;
+	if (Array.isArray(enumValues)) {
+		schema.enum = enumValues.includes(null) ? enumValues : [...enumValues, null];
+	}
+}
+
+function rewriteNullableScalarAnyOf(schema: Record<string, unknown>): void {
+	if (hasSchemaDefiningSibling(schema)) return;
+	const variants = schema.anyOf;
+	if (!Array.isArray(variants) || variants.length !== 2) return;
+
+	let scalarVariant: Record<string, unknown> | undefined;
+	let scalarType: string | undefined;
+	let sawNull = false;
+	for (const variant of variants) {
+		if (!isSchemaRecord(variant)) return;
+		if (isNullVariant(variant)) {
+			if (sawNull) return;
+			sawNull = true;
+			continue;
+		}
+		if (!isScalarVariant(variant) || scalarVariant) return;
+		scalarVariant = variant;
+		scalarType = variant.type;
+	}
+	if (!sawNull || !scalarVariant || !scalarType) return;
+
+	delete schema.anyOf;
+	copyNullableScalarConstraints(schema, scalarVariant);
+	schema.type = [scalarType, "null"];
+}
+
+/** 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;
+
+function normalizeArkPropertyComments(node: unknown): void {
+	if (Array.isArray(node)) {
+		for (const child of node) normalizeArkPropertyComments(child);
+		return;
+	}
+	if (!isSchemaRecord(node)) return;
+	const obj = node as Record<string, unknown>;
+
+	const properties = obj.properties;
+	if (isSchemaRecord(properties)) {
+		const required = Array.isArray(obj.required) ? obj.required : undefined;
+		if (required) {
+			obj.required = required.map(key => (typeof key === "string" ? parseArkObjectKey(key).name : key));
+		}
+		for (const key of Object.keys(properties)) {
+			const parsed = parseArkObjectKey(key);
+			const targetKey = parsed.name;
+			let propertySchema = properties[key];
+			if (parsed.description) {
+				propertySchema = withArkKeyDescription(propertySchema, parsed.description);
+				delete properties[key];
+				properties[targetKey] = propertySchema;
+			}
+			normalizeArkPropertyComments(propertySchema);
+		}
+	}
+
+	for (const key of SCHEMA_VALUE_KEYS) {
+		if (Object.hasOwn(obj, key)) normalizeArkPropertyComments(obj[key]);
+	}
+	for (const mapKey of SCHEMA_MAP_KEYS) {
+		if (mapKey === "properties") continue;
+		const map = obj[mapKey];
+		if (isSchemaRecord(map)) {
+			for (const key in map) normalizeArkPropertyComments(map[key]);
+		}
+	}
+	for (const arrayKey of SCHEMA_ARRAY_KEYS) {
+		const array = obj[arrayKey];
+		if (Array.isArray(array)) {
+			for (const child of array) normalizeArkPropertyComments(child);
+		}
+	}
+}
+
+/** 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;
+	return Object.keys(val).length === 0;
+}
+
+/**
+ * The single JSON Schema scalar `type` that describes every member of a
+ * homogeneous primitive enum, or `undefined` when the members are mixed,
+ * non-scalar (`null`/object/array), or the list is empty.
+ */
+function homogeneousEnumScalarType(values: readonly unknown[]): string | undefined {
+	if (values.length === 0) return undefined;
+	let inferred: string | undefined;
+	for (const value of values) {
+		let scalar: string | undefined;
+		switch (typeof value) {
+			case "string":
+				scalar = "string";
+				break;
+			case "boolean":
+				scalar = "boolean";
+				break;
+			case "number":
+				scalar = "number";
+				break;
+			default:
+				return undefined; // null / object / array — not a single scalar type
+		}
+		if (inferred === undefined) inferred = scalar;
+		else if (inferred !== scalar) return undefined; // mixed primitives
+	}
+	return inferred;
+}
+
+/**
+ * ArkType emits string-literal unions (and raw JSON-Schema tools can declare
+ * enums) as a bare `{ enum: [...] }` with no `type`. That is valid JSON Schema
+ * and accepted by OpenAI/Anthropic, but Gemini/Vertex — including the
+ * OpenAI-compatible gateways fronting it — reject a function-declaration enum
+ * that omits `type` ("schema didn't specify the schema type field"). Complete
+ * the node by inferring the scalar `type` when every member shares one.
+ */
+function inferBareEnumScalarType(obj: Record<string, unknown>): void {
+	if ("type" in obj || !Array.isArray(obj.enum)) return;
+	const inferred = homogeneousEnumScalarType(obj.enum);
+	if (inferred !== undefined) obj.type = inferred;
+}
+
+/**
+ * ArkType serializes a *described* literal union — `type.enumerated(...).describe(d)`
+ * or a `"a" | "b"` union carrying a description — as an `anyOf` of
+ * `{ const, description }` branches that repeat the description on every branch
+ * *and* the union root. The meta is distributed across the union's constituents
+ * at the type level (each `unit` node inherits it), so the duplication is baked
+ * in before serialization rather than added by this pipeline.
+ *
+ * Collapse such a homogeneous all-`const` union into one typed
+ * `{ type, enum, description }` node: a shorter wire and a single description in
+ * the place providers expect it. The collapse is conservative — applied only
+ * when it is lossless:
+ *   - every branch is a bare `{ const }` (optionally `{ const, description }`),
+ *   - all branch values share one scalar JSON type (so `enum` gets a `type`,
+ *     which Gemini/Vertex require),
+ *   - branch descriptions are either all absent or all identical,
+ * so a union whose branches carry *distinct* per-variant descriptions is left
+ * untouched (a flat `enum` has nowhere to keep them). The union root's own
+ * description wins when present; otherwise the shared branch description is kept.
+ */
+function collapseConstUnionAnyOf(obj: Record<string, unknown>): void {
+	// `hasSchemaDefiningSibling` already rejects a sibling `enum`/`const`/etc.; it
+	// does not list `type`, so guard it here — collapsing would overwrite a
+	// wrapper `type` constraint paired with the `anyOf`.
+	if (hasSchemaDefiningSibling(obj) || "type" in obj) return;
+	const variants = obj.anyOf;
+	if (!Array.isArray(variants) || variants.length < 2) return;
+
+	const values: unknown[] = [];
+	let branchDescription: string | undefined;
+	let describedCount = 0;
+	for (const variant of variants) {
+		if (!isSchemaRecord(variant) || !Object.hasOwn(variant, "const")) return;
+		for (const key in variant) {
+			if (key !== "const" && key !== "description") return; // extra constraints — not a bare const
+		}
+		const desc = variant.description;
+		if (typeof desc === "string") {
+			if (describedCount === 0) branchDescription = desc;
+			else if (desc !== branchDescription) return; // distinct per-variant descriptions — preserve them
+			describedCount++;
+		}
+		values.push(variant.const);
+	}
+	if (describedCount !== 0 && describedCount !== variants.length) return; // mixed described/undescribed
+	// A shared branch description that disagrees with the union root's own
+	// description would be silently dropped by the collapse — keep the anyOf so
+	// neither annotation is lost. (Equal descriptions, the ArkType case, collapse.)
+	if (
+		describedCount === variants.length &&
+		typeof obj.description === "string" &&
+		obj.description !== branchDescription
+	) {
+		return;
+	}
+
+	const scalarType = homogeneousEnumScalarType(values);
+	if (scalarType === undefined) return; // mixed / non-scalar (incl. null) — leave as anyOf
+
+	delete obj.anyOf;
+	obj.type = scalarType;
+	obj.enum = values;
+	if (typeof obj.description !== "string" && branchDescription !== undefined) {
+		obj.description = branchDescription;
+	}
+}
+
+function walk(node: unknown, zodCleanup: boolean): void {
+	if (Array.isArray(node)) {
+		for (const child of node) walk(child, zodCleanup);
+		return;
+	}
+	if (!node || typeof node !== "object") return;
+	const obj = node as Record<string, unknown>;
+	rewriteNullableScalarAnyOf(obj);
+	inferBareEnumScalarType(obj);
+	collapseConstUnionAnyOf(obj);
+
+	if (zodCleanup) {
+		// Drop noise injected for `z.number().int()`.
+		if (hasIntegerType(obj.type)) {
+			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], zodCleanup);
+}
+
+/**
+ * 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);
+	});
+}
+
+/**
+ * Recursively set `additionalProperties: false` on declared object nodes so the
+ * model-facing wire matches Zod's closed emission. Only nodes that declare
+ * `properties` and carry neither `additionalProperties` nor `patternProperties`
+ * are closed — open record/index nodes (which already carry one of those, e.g.
+ * `additionalProperties: true` after empty-schema normalization) stay open.
+ *
+ * Traverses only schema-valued positions via the shared traversal-key constants
+ * so it never descends into `default`/`examples`/`enum`/`const` instance data.
+ */
+function closeDeclaredObjects(node: unknown): void {
+	if (Array.isArray(node)) {
+		for (const child of node) closeDeclaredObjects(child);
+		return;
+	}
+	if (!node || typeof node !== "object") return;
+	const obj = node as Record<string, unknown>;
+
+	const isObjectType = obj.type === "object" || (Array.isArray(obj.type) && obj.type.includes("object"));
+	if (
+		isObjectType &&
+		obj.properties !== undefined &&
+		!("additionalProperties" in obj) &&
+		!("patternProperties" in obj)
+	) {
+		obj.additionalProperties = false;
+	}
+
+	for (const key of SCHEMA_VALUE_KEYS) {
+		if (Object.hasOwn(obj, key)) closeDeclaredObjects(obj[key]);
+	}
+	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>) closeDeclaredObjects((map as Record<string, unknown>)[k]);
+		}
+	}
+	for (const arrKey of SCHEMA_ARRAY_KEYS) {
+		const arr = obj[arrKey];
+		if (Array.isArray(arr)) for (const child of arr) closeDeclaredObjects(child);
+	}
+}
+
+/** A subschema admitting any JSON value: `{}` or boolean `true` (draft 2020-12 §4.3.1). */
+function isUnconstrainedSchema(val: unknown): boolean {
+	return val === true || isEmptyObject(val);
+}
+
+/**
+ * ArkType-only: prune the unconstrained branch ArkType emits for a `T | undefined`
+ * value-union (e.g. `{ id: "string | undefined" }`).
+ *
+ * `undefined` has no JSON Schema form, so `arkToWireSchema`'s `fallback` degrades the
+ * `undefined` arm to the unconstrained empty schema, producing
+ * `{ anyOf: [{ type: "string" }, {}] }`. That bare `{}`/`true` combiner branch makes
+ * the property match any value; strict providers (OpenAI/Codex) reject it ("Invalid
+ * schema for function ..."), and `enforceStrictSchema` waves the non-object `true`
+ * branch straight through, so the break only surfaces server-side. This drops the
+ * unconstrained branch(es) from every ArkType-emitted `anyOf`/`oneOf` and inlines the
+ * lone remaining concrete branch (keeping sibling keywords like `description`).
+ *
+ * `required` is deliberately left untouched: ArkType validates a `T | undefined` key
+ * as required-present (an absent key is rejected at runtime), so the wire must keep the
+ * key required to stay consistent with runtime validation — demoting it to optional
+ * would let the model omit the key (or, under strict-mode nullable wrapping, send
+ * `null`) and then fail ArkType validation.
+ *
+ * Scoped to `arkToWireSchema` and run before `normalizeEmptySchemas` so the
+ * provider-agnostic `{}`→`true` pass (issue #1179) still preserves intentional open
+ * unions in Zod / raw-JSON tools. Traverses only schema-valued positions so it never
+ * descends into `default`/`examples`/`enum`/`const` instance data.
+ */
+function pruneArkUndefinedUnionBranches(node: unknown): void {
+	if (Array.isArray(node)) {
+		for (const child of node) pruneArkUndefinedUnionBranches(child);
+		return;
+	}
+	if (!node || typeof node !== "object") return;
+	const obj = node as Record<string, unknown>;
+
+	for (const unionKey of ["anyOf", "oneOf"] as const) {
+		const branches = obj[unionKey];
+		if (!Array.isArray(branches)) continue;
+		const concrete = branches.filter(branch => !isUnconstrainedSchema(branch));
+		if (concrete.length === branches.length || concrete.length === 0) continue;
+		const only = concrete.length === 1 ? concrete[0] : undefined;
+		if (only !== undefined && isSchemaRecord(only)) {
+			delete obj[unionKey];
+			for (const key in only) {
+				if (!(key in obj)) obj[key] = only[key];
+			}
+		} else {
+			obj[unionKey] = concrete;
+		}
+	}
+
+	for (const key of SCHEMA_VALUE_KEYS) {
+		if (Object.hasOwn(obj, key)) pruneArkUndefinedUnionBranches(obj[key]);
+	}
+	for (const mapKey of SCHEMA_MAP_KEYS) {
+		const map = obj[mapKey];
+		if (map !== null && typeof map === "object" && !Array.isArray(map)) {
+			for (const key in map as Record<string, unknown>) {
+				pruneArkUndefinedUnionBranches((map as Record<string, unknown>)[key]);
+			}
+		}
+	}
+	for (const arrKey of SCHEMA_ARRAY_KEYS) {
+		const arr = obj[arrKey];
+		if (Array.isArray(arr)) for (const child of arr) pruneArkUndefinedUnionBranches(child);
+	}
+}
+
+/**
+ * Convert an ArkType schema into the JSON Schema shape providers consume.
+ *
+ * Mirrors {@link zodToWireSchema}: emit draft-2020-12, drop the `$schema`
+ * metadata, run the JSON-schema post-process (NOT the Zod-only cleanup), then
+ * close declared objects so the wire is `additionalProperties: false` like Zod.
+ *
+ * The `fallback` degrades any un-emittable node (a `.narrow()` predicate or a
+ * morph) to its underlying base schema instead of throwing — matching Zod,
+ * whose `.refine()`/`.transform()` likewise never appear in the wire schema.
+ */
+export function arkToWireSchema(schema: Type): Record<string, unknown> {
+	return stamp(schema, kArkWireSchema, s => {
+		const raw = s.toJsonSchema({ target: "draft-2020-12", fallback: ctx => ctx.base }) as Record<string, unknown>;
+		delete raw.$schema;
+		pruneArkUndefinedUnionBranches(raw);
+		const upgraded = postProcessJsonSchema(upgradeJsonSchemaTo202012(raw) as Record<string, unknown>);
+		closeDeclaredObjects(upgraded);
+		return upgraded;
+	});
+}
+
+/**
+ * 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).
+ *
+ * Zod schemas also receive Zod-artifact cleanup; both branches normalize
+ * schema-valued positions and nullable scalar unions.
+ */
+export function toolWireSchema(tool: Tool): Record<string, unknown> {
+	const params: TSchema = tool.parameters;
+	if (isArkSchema(params)) return arkToWireSchema(params);
+	if (isZodSchema(params)) return zodToWireSchema(params);
+	return stamp(params as Record<string, unknown>, kJsonWireSchema, p => {
+		const raw = isArkJsonAst(p) ? arkJsonAstToWire(p) : p;
+		const upgraded = upgradeJsonSchemaTo202012(raw) as Record<string, unknown>;
+		return postProcessJsonSchema(upgraded);
+	});
+}
+
+/**
+ * Schema-valued keywords whose value is a single subschema (or an array of
+ * subschemas — the recursion dispatches on array-ness, so tuple forms like
+ * draft-07 `items: []` are handled too). Covers the draft 2020-12 surface plus
+ * the legacy `additionalItems` that may survive an incomplete upgrade.
+ */
+const STRIP_SCHEMA_VALUE_KEYS = [
+	"additionalProperties",
+	"unevaluatedProperties",
+	"unevaluatedItems",
+	"items",
+	"additionalItems",
+	"contains",
+	"propertyNames",
+	"contentSchema",
+	"if",
+	"then",
+	"else",
+	"not",
+	"anyOf",
+	"oneOf",
+	"allOf",
+	"prefixItems",
+] as const;
+
+/** Keywords whose value is a `{ name: Schema }` map — names are NOT annotations. */
+const STRIP_SCHEMA_MAP_KEYS = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"] as const;
+
+/**
+ * Recursively strip human-readable `description` annotations from a JSON Schema,
+ * descending only through schema-valued keywords so a property literally named
+ * `"description"` inside a `properties`/`$defs` map keeps its schema (only its own
+ * annotation is dropped), and data-bearing keywords (`default`/`const`/`examples`)
+ * are never traversed. Mutates `node` in place — callers pass a clone.
+ */
+function stripSchemaDescriptionsInPlace(node: unknown): void {
+	if (Array.isArray(node)) {
+		for (const child of node) stripSchemaDescriptionsInPlace(child);
+		return;
+	}
+	if (!isSchemaRecord(node)) return;
+	delete node.description;
+	for (const key of STRIP_SCHEMA_VALUE_KEYS) {
+		if (Object.hasOwn(node, key)) stripSchemaDescriptionsInPlace(node[key]);
+	}
+	for (const mapKey of STRIP_SCHEMA_MAP_KEYS) {
+		const map = node[mapKey];
+		if (isSchemaRecord(map)) {
+			for (const key in map) stripSchemaDescriptionsInPlace(map[key]);
+		}
+	}
+}
+
+/**
+ * Return a deep clone of `schema` with every `description` annotation removed.
+ * The result is memoized on the input via a non-enumerable symbol (`stamp`) so
+ * repeated provider requests reuse the same stripped object; the input is never
+ * mutated, so the stamped `toolWireSchema` cache stays intact for
+ * system-prompt/UI rendering.
+ */
+export function stripSchemaDescriptions(schema: Record<string, unknown>): Record<string, unknown> {
+	return stamp(schema, kStrippedSchema, source => {
+		const clone = structuredClone(source);
+		stripSchemaDescriptionsInPlace(clone);
+		return clone;
+	});
+}
+
+/**
+ * Strip a tool's human-readable text from its provider-bound spec: empties the
+ * top-level `description` and removes nested schema `description` annotations.
+ * Used when the full tool catalog is rendered into the system prompt instead, so
+ * the descriptions ride the wire once (in the prompt) rather than duplicated on
+ * every tool definition. Parameters are resolved to wire JSON Schema and cloned,
+ * leaving the original tool objects and the stamped schema cache untouched.
+ */
+export function stripToolDescriptions(tools: readonly Tool[]): Tool[] {
+	return tools.map(tool => ({
+		...tool,
+		description: "",
+		parameters: stripSchemaDescriptions(toolWireSchema(tool)),
+	}));
+}