Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
ts 1,206 lines 43.8 KB
Raw
1 import { z } from 'zod/v3';
2 import { JsonSchemaRefResolutionError, JsonSchemaToZodError } from '../errors';
3 import { jsonSchemaToZod } from '@composio/json-schema-to-zod';
4 import logger from './logger';
5 import { isPlainObject } from './modifiers/FileToolModifier.utils.neutral';
6
7 const MAX_REF_CHAIN_DEPTH = 100;
8 const MAX_NODE_DEPTH = 512;
9 // Bounds on one null-acceptance check; past either, null is not proven accepted.
10 const MAX_NULL_CHECK_DEPTH = 64;
11 const MAX_NULL_CHECK_NODES = 2_000;
12 const CYCLE_BREAK_SENTINEL = { type: 'object', additionalProperties: true } as const;
13
14 /** Keywords whose value is a single subschema. */
15 const SCHEMA_KEYWORDS = new Set([
16 'additionalItems',
17 'additionalProperties',
18 'contains',
19 'contentSchema',
20 'else',
21 'if',
22 'not',
23 'propertyNames',
24 'then',
25 'unevaluatedItems',
26 'unevaluatedProperties',
27 ]);
28 /** Keywords whose value is an array of subschemas. */
29 const SCHEMA_ARRAY_KEYWORDS = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
30 /** Keywords whose value is a map from name to subschema. */
31 const SCHEMA_MAP_KEYWORDS = new Set([
32 '$defs',
33 'definitions',
34 'dependentSchemas',
35 'patternProperties',
36 'properties',
37 ]);
38 /** Keywords whose values are instance data, never subschemas. */
39 const INSTANCE_VALUE_KEYWORDS = new Set(['const', 'default', 'enum', 'examples']);
40
41 /**
42 * In-band hint attached to the cycle-break sentinel when lenient mode
43 * substitutes it for a dangling `$ref`. Makes the degradation visible to
44 * LLMs that read the wrapped tool's schema — without it the LLM sees a
45 * useless permissive object and no prose context. Wording is intentionally
46 * context-neutral ("Schema shape", not "Output shape") because the helper
47 * is used for both `inputParameters` and `outputParameters`. Overridden
48 * when the caller's `$ref` node carries its own `description` sibling
49 * (Draft 2020-12 sibling-keyword semantics).
50 */
51 const UNRESOLVED_REF_DESCRIPTION =
52 'Schema shape unresolved at the source — validate loosely. ' +
53 'See https://github.com/ComposioHQ/composio/issues/3307.';
54
55 /**
56 * Strategy for `dereferenceJsonSchema` when an internal `$ref` cannot be
57 * resolved (target missing under `$defs`/`definitions`, or a malformed
58 * pointer beneath the internal `#/` prefix).
59 *
60 * - `'throw'` (default): throw `JsonSchemaRefResolutionError`. Right for
61 * first-party / custom-tool schemas where a dangling `$ref` is a developer
62 * bug worth surfacing.
63 * - `'sentinel'`: replace the offending node with the cycle-break sentinel
64 * (`{ type: 'object', additionalProperties: true }`). Right for schemas
65 * sourced from an upstream service the caller cannot edit (e.g. an
66 * API-provided tool definition that emits `$ref` without a `$defs`
67 * block — see https://github.com/ComposioHQ/composio/issues/3307).
68 *
69 * Safety caps (`MAX_REF_CHAIN_DEPTH`, `MAX_NODE_DEPTH`) still throw in both
70 * modes; cycle handling (already permissive via `CYCLE_BREAK_SENTINEL`) is
71 * unaffected.
72 */
73 export type UnresolvedRefStrategy = 'throw' | 'sentinel';
74
75 /**
76 * Reason a `$ref` was replaced with the sentinel in `'sentinel'` mode.
77 * `onReplace` callbacks receive this so callers can attribute the
78 * fallback (e.g., warn at the offending tool slug).
79 */
80 export type UnresolvedRefReason = 'missing-target' | 'malformed-pointer';
81
82 export interface DereferenceJsonSchemaOptions {
83 onUnresolved?: UnresolvedRefStrategy;
84 /**
85 * Invoked once per replaced node in `'sentinel'` mode. The ref is the
86 * original pointer string from the schema; reason distinguishes a
87 * missing `$defs` target from a malformed pointer.
88 */
89 onReplace?: (ref: string, reason: UnresolvedRefReason) => void;
90 }
91 const POLLUTING_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
92 const REF_RESOLUTION_FIXES = [
93 'Ensure the $ref pointer matches a path in $defs or definitions',
94 'External $ref pointers (http://, https://, file://, …) are not resolved by the SDK',
95 ];
96
97 const decodePointerSegment = (segment: string): string =>
98 segment.replace(/~1/g, '/').replace(/~0/g, '~');
99
100 /**
101 * Tagged result of attempting to resolve a `$ref`. `failedAt` is populated
102 * only for the segment-walk path so strict-mode error meta stays identical
103 * to the pre-lenient-mode shape.
104 */
105 type ResolutionResult =
106 | { kind: 'ok'; value: unknown }
107 | { kind: 'unresolved'; reason: UnresolvedRefReason; failedAt?: string };
108
109 const tryStep = (cursor: unknown, segment: string): ResolutionResult => {
110 if (cursor === null || typeof cursor !== 'object') {
111 return { kind: 'unresolved', reason: 'missing-target', failedAt: segment };
112 }
113 if (Array.isArray(cursor)) {
114 const i = Number(segment);
115 if (!Number.isInteger(i) || i < 0 || i >= cursor.length) {
116 return { kind: 'unresolved', reason: 'missing-target', failedAt: segment };
117 }
118 return { kind: 'ok', value: cursor[i] };
119 }
120 const obj = cursor as Record<string, unknown>;
121 if (!Object.prototype.hasOwnProperty.call(obj, segment)) {
122 return { kind: 'unresolved', reason: 'missing-target', failedAt: segment };
123 }
124 return { kind: 'ok', value: obj[segment] };
125 };
126
127 const tryResolvePointer = (root: Record<string, unknown>, pointer: string): ResolutionResult => {
128 if (pointer === '#' || pointer === '') return { kind: 'ok', value: root };
129 if (!pointer.startsWith('#/')) {
130 return { kind: 'unresolved', reason: 'malformed-pointer' };
131 }
132 const segments = pointer.slice(2).split('/').map(decodePointerSegment);
133 let cursor: unknown = root;
134 for (const seg of segments) {
135 const step = tryStep(cursor, seg);
136 if (step.kind === 'unresolved') return step;
137 cursor = step.value;
138 }
139 return { kind: 'ok', value: cursor };
140 };
141
142 const throwResolutionError = (
143 pointer: string,
144 result: Extract<ResolutionResult, { kind: 'unresolved' }>
145 ): never => {
146 if (result.reason === 'malformed-pointer') {
147 throw new JsonSchemaRefResolutionError(`Unsupported $ref pointer: ${pointer}`, {
148 meta: { ref: pointer },
149 possibleFixes: REF_RESOLUTION_FIXES,
150 });
151 }
152 throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
153 meta: {
154 ref: pointer,
155 ...(result.failedAt !== undefined ? { failedAt: result.failedAt } : {}),
156 },
157 possibleFixes: REF_RESOLUTION_FIXES,
158 });
159 };
160
161 /**
162 * Inlines internal JSON Schema `$ref` pointers (`#/$defs/...` and legacy
163 * `#/definitions/...`) so the returned schema can be safely handed to
164 * consumers that don't tolerate unresolved references (e.g. AJV in
165 * `@mastra/schema-compat`). External (`http://`, `https://`, …) refs are
166 * left untouched. Cycles are broken with `{ type: 'object',
167 * additionalProperties: true }`. The input is never mutated.
168 *
169 * By default, unresolved internal refs throw `JsonSchemaRefResolutionError`.
170 * Pass `{ onUnresolved: 'sentinel' }` to replace the offending node with the
171 * cycle-break sentinel instead — appropriate for schemas sourced from an
172 * upstream service the caller cannot edit (the Composio API ships some
173 * `outputParameters` with a `$ref` into `#/$defs/...` but never declares
174 * `$defs`; see https://github.com/ComposioHQ/composio/issues/3307).
175 *
176 * @throws {JsonSchemaRefResolutionError} on malformed pointers, missing
177 * targets (strict mode only), or chains past the depth cap (both modes).
178 */
179 export function dereferenceJsonSchema<T = unknown>(
180 schema: T,
181 options?: DereferenceJsonSchemaOptions
182 ): T {
183 if (!isPlainObject(schema)) return schema;
184
185 const strategy: UnresolvedRefStrategy = options?.onUnresolved ?? 'throw';
186 const onReplace = options?.onReplace;
187
188 const root = schema as Record<string, unknown>;
189 const visiting = new WeakSet<object>();
190
191 // POLLUTING_KEYS filter prevents an attacker-shaped $defs entry from altering
192 // the cloned node's prototype.
193 const cloneChildren = (
194 obj: Record<string, unknown>,
195 visitedRefs: ReadonlySet<string>,
196 chainDepth: number,
197 nodeDepth: number
198 ): Record<string, unknown> =>
199 Object.fromEntries(
200 Object.entries(obj)
201 .filter(([k]) => !POLLUTING_KEYS.has(k))
202 .map(([k, v]) => [k, walk(v, visitedRefs, chainDepth, nodeDepth + 1)])
203 );
204
205 // `function` (not `const`) so `cloneChildren` above can call it via hoisting.
206 function walk(
207 node: unknown,
208 visitedRefs: ReadonlySet<string>,
209 chainDepth: number,
210 nodeDepth: number
211 ): unknown {
212 if (nodeDepth >= MAX_NODE_DEPTH) {
213 throw new JsonSchemaRefResolutionError(
214 `JSON Schema node depth exceeded cap (${MAX_NODE_DEPTH})`,
215 { possibleFixes: REF_RESOLUTION_FIXES }
216 );
217 }
218 if (Array.isArray(node)) {
219 if (visiting.has(node)) return { ...CYCLE_BREAK_SENTINEL };
220 visiting.add(node);
221 try {
222 return node.map(item => walk(item, visitedRefs, chainDepth, nodeDepth + 1));
223 } finally {
224 visiting.delete(node);
225 }
226 }
227 if (!isPlainObject(node)) return node;
228 if (visiting.has(node)) return { ...CYCLE_BREAK_SENTINEL };
229 visiting.add(node);
230 try {
231 const ref = typeof node.$ref === 'string' ? node.$ref : null;
232 // External refs and non-$ref nodes both pass through the same clone path.
233 if (ref === null || !ref.startsWith('#')) {
234 if (ref !== null) {
235 // Audit signal for security-sensitive deployments: a downstream
236 // resolver may fetch this and trigger SSRF or local-file disclosure.
237 logger.warn(`Leaving external $ref untouched: ${ref}`);
238 }
239 return cloneChildren(node, visitedRefs, chainDepth, nodeDepth);
240 }
241
242 if (chainDepth >= MAX_REF_CHAIN_DEPTH) {
243 throw new JsonSchemaRefResolutionError(
244 `JSON Schema $ref chain exceeded depth cap (${MAX_REF_CHAIN_DEPTH}): ${ref}`,
245 { meta: { ref }, possibleFixes: REF_RESOLUTION_FIXES }
246 );
247 }
248 if (visitedRefs.has(ref)) return { ...CYCLE_BREAK_SENTINEL };
249
250 const result = tryResolvePointer(root, ref);
251 let target: unknown;
252 if (result.kind === 'ok') {
253 target = result.value;
254 } else if (strategy === 'sentinel') {
255 // Lenient mode: replace the unresolved branch with the same
256 // permissive sentinel used for cycles, and notify the caller so
257 // they can emit a one-shot warn at the offending tool surface.
258 // The injected `description` gives the LLM an in-band signal that
259 // the branch is opaque; sibling-merge below will overwrite it with
260 // a caller-provided description if the original node has one.
261 onReplace?.(ref, result.reason);
262 target = { ...CYCLE_BREAK_SENTINEL, description: UNRESOLVED_REF_DESCRIPTION };
263 } else {
264 throwResolutionError(ref, result);
265 }
266 const nextRefs = new Set(visitedRefs).add(ref);
267 const resolved = walk(target, nextRefs, chainDepth + 1, nodeDepth + 1);
268
269 // Shallow-merge sibling keywords (Draft 2020-12 semantics: siblings win
270 // on collision). Draft 7 ignores siblings entirely, but the Composio
271 // tool surface admits both drafts so we honor siblings for safety.
272 const siblings: Record<string, unknown> = { ...node };
273 delete siblings.$ref;
274 if (Object.keys(siblings).length === 0 || !isPlainObject(resolved)) {
275 return resolved;
276 }
277 return { ...resolved, ...cloneChildren(siblings, visitedRefs, chainDepth, nodeDepth) };
278 } finally {
279 visiting.delete(node);
280 }
281 }
282
283 const out = walk(root, new Set(), 0, 0);
284 if (isPlainObject(out)) {
285 delete out.$defs;
286 delete out.definitions;
287 }
288 return out as T;
289 }
290
291 /**
292 * Returns a deep-cloned JSON Schema in which every node that carries a
293 * `properties` keyword also carries `type: "object"` when it has no explicit
294 * `type`. OpenAI tolerates the omission, but Google Gemini enforces OpenAPI
295 * 3.0 strictly and rejects function declarations whose nested objects are
296 * missing the `type` (see https://github.com/ComposioHQ/composio/issues/4022).
297 *
298 * The function follows JSON Schema's schema-bearing keywords while keeping
299 * property maps and instance values as containers. Nodes that already declare
300 * a `type` are left untouched.
301 */
302 export function ensureObjectTypeOnProperties<T = unknown>(schema: T): T {
303 type WalkMode = 'schema' | 'schema-array' | 'schema-map' | 'dependencies-map' | 'value';
304
305 function walk(value: unknown, mode: WalkMode, depth = 0): unknown {
306 if (depth > MAX_NODE_DEPTH) {
307 throw new RangeError(`JSON Schema exceeds maximum nesting depth of ${MAX_NODE_DEPTH}`);
308 }
309
310 if (Array.isArray(value)) {
311 const itemMode = mode === 'schema-array' ? 'schema' : 'value';
312 return value.map(item => walk(item, itemMode, depth + 1));
313 }
314
315 if (!isPlainObject(value)) return value;
316
317 const clone: Record<string, unknown> = {};
318 for (const [key, child] of Object.entries(value)) {
319 let childMode: WalkMode = 'value';
320 if (mode === 'schema-map') {
321 childMode = 'schema';
322 } else if (mode === 'dependencies-map') {
323 childMode = Array.isArray(child) ? 'value' : 'schema';
324 } else if (mode === 'schema') {
325 if (SCHEMA_MAP_KEYWORDS.has(key)) {
326 childMode = 'schema-map';
327 } else if (SCHEMA_ARRAY_KEYWORDS.has(key) || (key === 'items' && Array.isArray(child))) {
328 childMode = 'schema-array';
329 } else if (SCHEMA_KEYWORDS.has(key) || key === 'items') {
330 childMode = 'schema';
331 } else if (key === 'dependencies') {
332 childMode = 'dependencies-map';
333 }
334 }
335
336 Object.defineProperty(clone, key, {
337 configurable: true,
338 enumerable: true,
339 value: walk(child, childMode, depth + 1),
340 writable: true,
341 });
342 }
343
344 if (mode === 'schema' && clone.properties !== undefined && clone.type === undefined) {
345 clone.type = 'object';
346 }
347
348 return clone;
349 }
350
351 return walk(schema, 'schema') as T;
352 }
353
354 /**
355 * Returns a deep-cloned JSON Schema whose `required` arrays contain each entry
356 * at most once. Duplicate entries are invalid in JSON Schema 2020-12 but do
357 * not change the schema's meaning, so preserving the first occurrence is safe.
358 *
359 * Tool schemas originate both from the Composio API and direct provider calls.
360 * Keeping this normalization provider-agnostic lets every SDK provider receive
361 * canonical API schemas, while providers that further transform a schema can
362 * reapply it at their own emission boundary.
363 */
364 export function deduplicateJsonSchemaRequiredArrays<T = unknown>(schema: T): T {
365 const seenSchemaValues = new WeakMap<object, unknown>();
366 const seenInstanceValues = new WeakMap<object, unknown>();
367
368 function walk(value: unknown, isSchema: boolean, depth = 0): unknown {
369 if (depth > MAX_NODE_DEPTH) {
370 throw new RangeError(`JSON Schema exceeds maximum nesting depth of ${MAX_NODE_DEPTH}`);
371 }
372
373 const seen = isSchema ? seenSchemaValues : seenInstanceValues;
374
375 if (Array.isArray(value)) {
376 const existing = seen.get(value);
377 if (existing) return existing;
378
379 const clone: unknown[] = [];
380 seen.set(value, clone);
381 for (const item of value) {
382 clone.push(walk(item, isSchema, depth + 1));
383 }
384 return clone;
385 }
386
387 if (!isPlainObject(value)) return value;
388
389 const existing = seen.get(value);
390 if (existing) return existing;
391
392 const clone: Record<string, unknown> = {};
393 seen.set(value, clone);
394 for (const [key, child] of Object.entries(value)) {
395 Object.defineProperty(clone, key, {
396 configurable: true,
397 enumerable: true,
398 value:
399 isSchema && key === 'required' && Array.isArray(child)
400 ? [...new Set(walk(child, false, depth + 1) as unknown[])]
401 : walk(child, isSchema && !INSTANCE_VALUE_KEYWORDS.has(key), depth + 1),
402 writable: true,
403 });
404 }
405 return clone;
406 }
407
408 return walk(schema, true) as T;
409 }
410
411 /**
412 * Removes all non-required properties from the schema
413 *
414 * if no items are required, the schema is returned as is
415 * @param schema - The JSON schema to remove non-required properties from
416 * @returns The JSON schema with all non-required properties removed
417 */
418 export const removeNonRequiredProperties = <
419 T extends {
420 type: 'object';
421 properties: Record<string, unknown>;
422 required?: string[];
423 additionalProperties?: unknown;
424 },
425 >(
426 schema: T
427 ): T => {
428 if (schema && schema.type === 'object' && (schema.required as string[])?.length) {
429 schema.properties = Object.fromEntries(
430 Object.entries(schema.properties || {}).filter(([key]) =>
431 (schema.required as string[]).includes(key)
432 )
433 );
434 }
435 // In strict mode, we don't allow additional properties
436 schema.additionalProperties = false;
437 return schema as T;
438 };
439
440 /**
441 * Convert a JSON schema to a Zod schema
442 * @param jsonSchema - The JSON schema to convert
443 * @param strict - Eliminates all non-required properties from the schema
444 * @returns The Zod schema
445 *
446 * @throws {JsonSchemaToZodError} If the JSON schema is invalid
447 *
448 * @example
449 * ```ts
450 * const zodSchema = jsonSchemaToZodSchema({
451 * type: 'object',
452 * properties: {
453 * name: { type: 'string' },
454 * },
455 * });
456 *
457 * console.log(zodSchema);
458 * ```
459 *
460 * @example
461 * ```ts
462 * const zodSchema = jsonSchemaToZodSchema({
463 * type: 'object',
464 * properties: {
465 * name: { type: 'string' },
466 * age: { type: 'number' },
467 * },
468 * required: ['name'],
469 * }, { strict: true });
470 *
471 * console.log(zodSchema);
472 *
473 * // Output:
474 * // z.object({
475 * // name: z.string(),
476 * // })
477 * ```
478 */
479 export function jsonSchemaToZodSchema<T extends z.ZodTypeAny>(
480 jsonSchema: Record<string, unknown>,
481 { strict }: { strict?: boolean } = {
482 strict: false,
483 }
484 ): T {
485 try {
486 let schema = jsonSchema;
487 // Remove all non-required properties from the schema if strict is true
488 if (strict && schema) {
489 schema = removeNonRequiredProperties(
490 schema as {
491 type: 'object';
492 properties: Record<string, unknown>;
493 required?: string[] | undefined;
494 }
495 );
496 }
497 // Convert the JSON schema properties to Zod schema
498 const zodSchema = jsonSchemaToZod(schema) as T;
499 return zodSchema;
500 } catch (error) {
501 // The cause names the offending property path; surface it in the message
502 // so a single malformed property is identifiable without unwrapping.
503 const detail = error instanceof Error ? `: ${error.message}` : '';
504 throw new JsonSchemaToZodError(`Failed to convert JSON Schema to Zod Schema${detail}`, {
505 cause: error,
506 });
507 }
508 }
509
510 /**
511 * Reason recorded when strict normalization rewrites a schema node. Every
512 * rewrite is lossless: the model can still express the same values.
513 *
514 * - `optional-property-nullable` — a property missing from `required` was
515 * added to it and widened to accept `null`, the emulation of optional
516 * fields that OpenAI structured outputs document.
517 * - `unsupported-keyword-stripped` — an annotation keyword the API rejects
518 * (`default`, `examples`, or a string `format` outside the accepted list)
519 * was removed.
520 * - `one-of-converted` — `oneOf` (unsupported) became `anyOf`.
521 * - `nullable-converted` — OpenAPI `nullable: true`, which Anthropic rejects
522 * on an object, became a `null` member of `type` or a null branch.
523 */
524 export type StrictSchemaChangeReason =
525 | 'optional-property-nullable'
526 | 'unsupported-keyword-stripped'
527 | 'one-of-converted'
528 | 'nullable-converted';
529
530 /** A single lossless rewrite applied by {@link toStrictJsonSchema}. */
531 export interface StrictSchemaChange {
532 /** Path to the changed node relative to the root, e.g. `properties.cfg.items`. */
533 path: string;
534 reason: StrictSchemaChangeReason;
535 /** Human-readable detail about what specifically changed. */
536 detail?: string;
537 }
538
539 /**
540 * A schema construct strict structured outputs cannot express. Rewriting it
541 * would change what the tool accepts, so it is reported instead; providers
542 * send such a tool without strict mode.
543 */
544 export interface StrictSchemaIncompatibility {
545 /** Path to the offending node relative to the root. */
546 path: string;
547 /** The keyword (or `$ref`) that has no strict-mode equivalent. */
548 keyword: string;
549 detail: string;
550 }
551
552 /** Result of {@link toStrictJsonSchema}. */
553 export interface StrictJsonSchemaResult {
554 /**
555 * The strict schema. Only usable when `unsupported` is empty; otherwise it
556 * is best-effort and the original schema should be sent without strict mode.
557 */
558 schema: Record<string, unknown>;
559 /**
560 * The input schema the rewrite was computed from. Optionality is decided
561 * against this schema, so it is what `omitNullToolArguments` needs.
562 */
563 source: Record<string, unknown>;
564 /** Lossless rewrites, capped at 50 entries; see `totalChanges`. */
565 changes: StrictSchemaChange[];
566 totalChanges: number;
567 /** Constructs strict mode cannot express. Non-empty means "do not use `schema`". */
568 unsupported: StrictSchemaIncompatibility[];
569 }
570
571 const MAX_STRICT_CHANGES = 50;
572
573 /** Annotation-only keywords OpenAI structured outputs rejects; safe to strip. */
574 const STRICT_STRIP_KEYWORDS = new Set(['examples', 'default']);
575
576 /**
577 * The `format` values OpenAI structured outputs accepts on a string schema,
578 * matched case-sensitively; any other value there is rejected with a 400.
579 * Formats on number and integer schemas are not checked.
580 */
581 const STRICT_STRING_FORMATS = new Set([
582 'date-time',
583 'time',
584 'date',
585 'duration',
586 'email',
587 'hostname',
588 'ipv4',
589 'ipv6',
590 'uuid',
591 ]);
592
593 /** Whether a `type` value admits strings; an absent `type` admits every type. */
594 const admitsString = (type: unknown): boolean =>
595 type === undefined || type === 'string' || (Array.isArray(type) && type.includes('string'));
596
597 /** Keywords OpenAI structured outputs reject and that have no lossless rewrite. */
598 const STRICT_UNSUPPORTED_KEYWORDS = [
599 'allOf',
600 'prefixItems',
601 'additionalItems',
602 'contains',
603 'dependencies',
604 'dependentSchemas',
605 'else',
606 'if',
607 'not',
608 'propertyNames',
609 'then',
610 'unevaluatedItems',
611 'unevaluatedProperties',
612 ];
613
614 /** Whether a `type` value declares exactly the object type. */
615 const isObjectType = (type: unknown): boolean =>
616 type === 'object' || (Array.isArray(type) && type.length === 1 && type[0] === 'object');
617
618 type StrictWalkMode = 'schema' | 'schema-array' | 'schema-map' | 'value';
619
620 const joinPath = (parent: string, key: string): string => (parent ? `${parent}.${key}` : key);
621
622 /**
623 * Sets an own property regardless of its name: a plain assignment to a key
624 * such as `__proto__` would set the prototype instead of storing the value.
625 */
626 function setOwn(target: Record<string, unknown>, key: string, value: unknown): void {
627 Object.defineProperty(target, key, {
628 configurable: true,
629 enumerable: true,
630 value,
631 writable: true,
632 });
633 }
634
635 /**
636 * The only keywords that can reject a `null` instance; every other keyword
637 * constrains strings, numbers, arrays or objects and ignores `null`.
638 */
639 const NULL_CONSTRAINT_KEYWORDS = [
640 'type',
641 'enum',
642 'const',
643 '$ref',
644 'anyOf',
645 'oneOf',
646 'allOf',
647 'not',
648 'if',
649 'then',
650 'else',
651 ] as const;
652
653 /**
654 * Widens a property schema so that `null` is an accepted value while keeping
655 * every other constraint it declares. A node whose only obstacle is `type` or
656 * `anyOf` is widened in place. Anything else is wrapped whole, because JSON
657 * Schema keywords apply together: adding `null` to `type` does not lift a
658 * sibling `enum`. `acceptsNull` must answer for the strict output.
659 */
660 function widenToNullable(
661 node: Record<string, unknown>,
662 acceptsNull: (schema: unknown) => boolean
663 ): Record<string, unknown> {
664 if (acceptsNull(node)) return node;
665 const constraints = NULL_CONSTRAINT_KEYWORDS.filter(key => key in node);
666 if (constraints.length === 1 && constraints[0] === 'type') {
667 const members = Array.isArray(node.type) ? node.type : [node.type];
668 return { ...node, type: [...members, 'null'] };
669 }
670 if (constraints.length === 1 && constraints[0] === 'anyOf' && Array.isArray(node.anyOf)) {
671 return { ...node, anyOf: [...node.anyOf, { type: 'null' }] };
672 }
673 const { description, title, ...rest } = node;
674 return {
675 ...(description !== undefined ? { description } : {}),
676 ...(title !== undefined ? { title } : {}),
677 anyOf: [rest, { type: 'null' }],
678 };
679 }
680
681 /**
682 * Follows local `$ref` pointers from `node` until a concrete schema node is
683 * reached. Unresolvable or over-long chains return the last node seen.
684 */
685 function resolveLocalRefs(node: unknown, root: Record<string, unknown>): unknown {
686 let current = node;
687 for (let hops = 0; hops < MAX_REF_CHAIN_DEPTH; hops++) {
688 if (!isPlainObject(current) || typeof current.$ref !== 'string') return current;
689 const resolution = tryResolvePointer(root, current.$ref);
690 if (resolution.kind === 'unresolved') return current;
691 current = resolution.value;
692 }
693 return current;
694 }
695
696 /**
697 * Creates the check for whether schemas of one document accept `null` as an
698 * instance: every keyword in `NULL_CONSTRAINT_KEYWORDS` that is present must
699 * accept it. This is the single definition of null acceptance; the strict
700 * rewrite and `omitNullToolArguments` both decide with it.
701 *
702 * `strictOutput` answers for the schema `toStrictJsonSchema` emits instead of
703 * the one it was given: the rewrite types every node that declares
704 * `properties` as an object, so such a node stops accepting null.
705 *
706 * `followRefs: false` makes every `$ref` reject null without resolving it.
707 * Folding `nullable` needs that, because a `$ref` can lead back to the node
708 * being folded, whose source still accepts null. It costs at most a
709 * redundant null branch.
710 *
711 * One check serves a whole document, and an answer is computed once per node.
712 * A reference cycle never yields a null by itself, so a node met again while
713 * it is being evaluated counts as rejecting. An answer that leans on that is
714 * provisional until the node it leans on is done: it is kept if that node
715 * does reject null and discarded otherwise.
716 *
717 * Each check is bounded in depth and in nodes visited. A check that meets a
718 * bound proves nothing, so it rejects null whatever its other branches say,
719 * which costs at most a redundant null branch or a dropped null. The nodes it
720 * went through stay marked as unproven, so a later check that reaches one of
721 * them neither repeats the work nor trusts the answer.
722 */
723 function createNullCheck(
724 root: Record<string, unknown>,
725 strictOutput = false,
726 followRefs = true
727 ): (schema: unknown) => boolean {
728 // Markers for what an answer leans on, besides the depth of a node on the path.
729 const NOTHING = MAX_NULL_CHECK_DEPTH + 1;
730 const A_BOUND = -1;
731 const answers = new Map<object, { answer: boolean; leansOn: number }>();
732 // Nodes whose answer is provisional, oldest first.
733 const provisional: object[] = [];
734 // Nodes being evaluated, mapped to their depth on the current path.
735 const path = new Map<object, number>();
736 // Depths of the path nodes that were met again below themselves.
737 const metAgain = new Set<number>();
738 let budget = 0;
739 // Shallowest thing the answers used since the last reset lean on.
740 let leansOn = NOTHING;
741
742 const accepts = (schema: unknown): boolean => {
743 if (typeof schema === 'boolean') return schema;
744 if (!isPlainObject(schema)) return true;
745 const remembered = answers.get(schema);
746 if (remembered !== undefined) {
747 if (path.size === 0) return remembered.answer && remembered.leansOn !== A_BOUND;
748 leansOn = Math.min(leansOn, remembered.leansOn);
749 return remembered.answer;
750 }
751 const onPath = path.get(schema);
752 if (onPath !== undefined) {
753 metAgain.add(onPath);
754 leansOn = Math.min(leansOn, onPath);
755 return false;
756 }
757 const depth = path.size;
758 if (depth === 0) budget = MAX_NULL_CHECK_NODES;
759 if (depth >= MAX_NULL_CHECK_DEPTH || budget <= 0) {
760 leansOn = A_BOUND;
761 return false;
762 }
763 budget -= 1;
764
765 const outer = leansOn;
766 leansOn = NOTHING;
767 const mark = provisional.length;
768 path.set(schema, depth);
769 let answer = keywordsAccept(schema);
770 path.delete(schema);
771
772 const own = leansOn;
773 const settled = own >= depth;
774 const below = provisional.splice(mark);
775 if (answer && metAgain.has(depth)) {
776 // The answers below took this node for rejecting null.
777 for (const other of below) answers.delete(other);
778 } else {
779 for (const other of below) {
780 const entry = answers.get(other);
781 if (entry === undefined) continue;
782 if (settled) {
783 entry.leansOn = NOTHING;
784 } else {
785 if (entry.leansOn >= depth) entry.leansOn = own;
786 provisional.push(other);
787 }
788 }
789 }
790 metAgain.delete(depth);
791
792 if (depth === 0 && own === A_BOUND) answer = false;
793 answers.set(schema, { answer, leansOn: settled ? NOTHING : own });
794 if (!settled) provisional.push(schema);
795 leansOn = settled ? outer : Math.min(outer, own);
796 if (depth === 0) {
797 // Whatever is still provisional leans on a bound, and stays so.
798 provisional.length = 0;
799 leansOn = NOTHING;
800 }
801 return answer;
802 };
803
804 const keywordsAccept = (node: Record<string, unknown>): boolean => {
805 // OpenAPI `nullable: true` admits null whatever the other keywords say,
806 // as the Zod conversion reads it.
807 if (node.nullable === true) return true;
808 if (typeof node.type === 'string' && node.type !== 'null') return false;
809 if (Array.isArray(node.type) && !node.type.includes('null')) return false;
810 if (strictOutput && !('type' in node) && isPlainObject(node.properties)) return false;
811 if (Array.isArray(node.enum) && !node.enum.includes(null)) return false;
812 if ('const' in node && node.const !== null) return false;
813 if ('$ref' in node) {
814 if (!followRefs) return false;
815 const resolution =
816 typeof node.$ref === 'string' ? tryResolvePointer(root, node.$ref) : undefined;
817 if (resolution === undefined || resolution.kind === 'unresolved') return false;
818 if (!accepts(resolution.value)) return false;
819 }
820 if (Array.isArray(node.anyOf) && !node.anyOf.some(accepts)) return false;
821 if (Array.isArray(node.oneOf)) {
822 const matches = node.oneOf.filter(accepts).length;
823 // The strict rewrite turns oneOf into anyOf.
824 if (matches === 0 || (matches > 1 && !strictOutput)) return false;
825 }
826 if (Array.isArray(node.allOf) && !node.allOf.every(accepts)) return false;
827 if ('not' in node && accepts(node.not)) return false;
828 if ('if' in node) {
829 const branch = accepts(node.if) ? 'then' : 'else';
830 if (branch in node && !accepts(node[branch])) return false;
831 }
832 return true;
833 };
834
835 return accepts;
836 }
837
838 /**
839 * Normalizes a tool parameter schema for OpenAI structured outputs
840 * (`strict: true`) at every depth, following the contract OpenAI documents:
841 *
842 * - every object lists all of its properties in `required` and sets
843 * `additionalProperties: false`;
844 * - properties that were optional stay available and are widened to accept
845 * `null` (`type: ['string', 'null']`, or an extra `anyOf` branch) — the
846 * documented way to emulate optional fields. Nothing is dropped, so the
847 * model keeps every parameter it could pass before. A `null` the model
848 * sends for such a property means "omitted"; the strict providers drop it
849 * before executing the tool (see {@link omitNullToolArguments});
850 * - `type` arrays are kept as-is (the API accepts them); `oneOf` becomes
851 * `anyOf`; `default`, `examples`, and a string `format` the API does
852 * not accept are stripped; OpenAPI `nullable` is stripped too, and a
853 * node that set it to `true` is widened to accept `null`;
854 * - local `$ref`s into `$defs`/`definitions` are kept (the API supports
855 * them, including recursion) and the definitions themselves are
856 * normalized; an optional `$ref` property is widened with an `anyOf`
857 * null branch;
858 * - constructs strict mode cannot express — objects that accept arbitrary
859 * keys (schema-valued or `true` `additionalProperties`, `patternProperties`,
860 * property-less free-form objects), boolean subschemas, `allOf`,
861 * `prefixItems`, tuple-form `items`, conditional and dependency keywords,
862 * external or dangling `$ref`s, and a non-object root — are reported in
863 * `unsupported` rather than rewritten into something narrower. Callers send
864 * such a tool without strict mode.
865 *
866 * The input is never mutated. Every rewrite is recorded in `changes` (capped
867 * at 50 entries; `totalChanges` carries the real count), and `required`
868 * arrays are de-duplicated at the end.
869 */
870 export function toStrictJsonSchema(schema: unknown): StrictJsonSchemaResult {
871 const changes: StrictSchemaChange[] = [];
872 const unsupported: StrictSchemaIncompatibility[] = [];
873 // Resolved references, re-checked against the rewritten schema.
874 const references: { path: string; ref: string }[] = [];
875 let totalChanges = 0;
876 const recordChange = (change: StrictSchemaChange): void => {
877 totalChanges += 1;
878 if (changes.length < MAX_STRICT_CHANGES) changes.push(change);
879 };
880
881 const root: Record<string, unknown> = isPlainObject(schema) ? schema : {};
882 const acceptsNullInOutput = createNullCheck(root, true);
883 const acceptsNullWithoutRefs = createNullCheck(root, true, false);
884
885 function walkChildren(
886 node: Record<string, unknown>,
887 mode: StrictWalkMode,
888 depth: number,
889 path: string
890 ): Record<string, unknown> {
891 const clone: Record<string, unknown> = {};
892 for (const [key, child] of Object.entries(node)) {
893 let childMode: StrictWalkMode = 'value';
894 if (mode === 'schema-map') {
895 childMode = 'schema';
896 } else if (mode === 'schema' && !INSTANCE_VALUE_KEYWORDS.has(key)) {
897 if (SCHEMA_MAP_KEYWORDS.has(key)) {
898 childMode = 'schema-map';
899 } else if (SCHEMA_ARRAY_KEYWORDS.has(key) || (key === 'items' && Array.isArray(child))) {
900 childMode = 'schema-array';
901 } else if (SCHEMA_KEYWORDS.has(key) || key === 'items') {
902 childMode = 'schema';
903 }
904 }
905
906 if (childMode === 'schema-map' && isPlainObject(child)) {
907 const mapClone: Record<string, unknown> = {};
908 for (const [name, subSchema] of Object.entries(child)) {
909 setOwn(
910 mapClone,
911 name,
912 walk(subSchema, 'schema', depth + 1, joinPath(joinPath(path, key), name))
913 );
914 }
915 setOwn(clone, key, mapClone);
916 continue;
917 }
918 setOwn(clone, key, walk(child, childMode, depth + 1, joinPath(path, key)));
919 }
920 return clone;
921 }
922
923 function walk(value: unknown, mode: StrictWalkMode, depth: number, path: string): unknown {
924 if (depth > MAX_NODE_DEPTH) {
925 throw new RangeError(`JSON Schema exceeds maximum nesting depth of ${MAX_NODE_DEPTH}`);
926 }
927 if (Array.isArray(value)) {
928 const itemMode = mode === 'schema-array' ? 'schema' : 'value';
929 return value.map((item, index) => walk(item, itemMode, depth + 1, `${path}[${index}]`));
930 }
931 if (!isPlainObject(value) || mode === 'value') return value;
932
933 const node: Record<string, unknown> = {};
934 for (const [key, child] of Object.entries(value)) {
935 if (key === 'nullable') continue;
936 if (STRICT_STRIP_KEYWORDS.has(key)) {
937 recordChange({
938 path,
939 reason: 'unsupported-keyword-stripped',
940 detail: `keyword "${key}" removed`,
941 });
942 continue;
943 }
944 if (
945 key === 'format' &&
946 typeof child === 'string' &&
947 !STRICT_STRING_FORMATS.has(child) &&
948 admitsString(value.type)
949 ) {
950 recordChange({
951 path,
952 reason: 'unsupported-keyword-stripped',
953 detail: `format "${child}" removed`,
954 });
955 continue;
956 }
957 setOwn(node, key, child);
958 }
959 if (Array.isArray(node.oneOf) && node.anyOf === undefined) {
960 node.anyOf = node.oneOf;
961 delete node.oneOf;
962 recordChange({ path, reason: 'one-of-converted', detail: 'oneOf became anyOf' });
963 }
964 for (const keyword of STRICT_UNSUPPORTED_KEYWORDS) {
965 if (node[keyword] !== undefined) {
966 unsupported.push({
967 path,
968 keyword,
969 detail: `"${keyword}" has no strict-mode equivalent`,
970 });
971 }
972 }
973 if (node.oneOf !== undefined) {
974 unsupported.push({ path, keyword: 'oneOf', detail: 'oneOf beside anyOf cannot be merged' });
975 }
976 if (Array.isArray(node.items)) {
977 unsupported.push({
978 path,
979 keyword: 'items',
980 detail: 'tuple-form items has no strict-mode equivalent',
981 });
982 } else if (typeof node.items === 'boolean') {
983 unsupported.push({ path, keyword: 'items', detail: 'boolean subschema' });
984 }
985 if (node.properties !== undefined && !isPlainObject(node.properties)) {
986 unsupported.push({ path, keyword: 'properties', detail: 'properties is not an object' });
987 }
988
989 const normalized = normalizeNode(node, mode, depth, path);
990 if (!('nullable' in value)) return normalized;
991 const widened =
992 value.nullable === true ? widenToNullable(normalized, acceptsNullWithoutRefs) : normalized;
993 recordChange(
994 widened === normalized
995 ? { path, reason: 'unsupported-keyword-stripped', detail: 'keyword "nullable" removed' }
996 : { path, reason: 'nullable-converted', detail: 'nullable became a null type' }
997 );
998 return widened;
999 }
1000
1001 function normalizeNode(
1002 node: Record<string, unknown>,
1003 mode: StrictWalkMode,
1004 depth: number,
1005 path: string
1006 ): Record<string, unknown> {
1007 const out = walkChildren(node, mode, depth, path);
1008
1009 if (typeof node.$ref === 'string') {
1010 const resolution =
1011 node.$ref === '#' || node.$ref.startsWith('#/')
1012 ? tryResolvePointer(root, node.$ref)
1013 : ({ kind: 'unresolved', reason: 'malformed-pointer' } as const);
1014 if (resolution.kind === 'unresolved') {
1015 unsupported.push({
1016 path,
1017 keyword: '$ref',
1018 detail: `unresolved $ref "${node.$ref}"`,
1019 });
1020 } else {
1021 references.push({ path, ref: node.$ref });
1022 }
1023 // The referenced definition is normalized where it is declared.
1024 return out;
1025 }
1026
1027 const declaresObjectType =
1028 out.type === 'object' || (Array.isArray(out.type) && out.type.includes('object'));
1029 if (!declaresObjectType && !isPlainObject(out.properties)) return out;
1030 if (out.properties !== undefined && !isPlainObject(out.properties)) return out;
1031
1032 const properties: Record<string, unknown> = {};
1033 if (isPlainObject(out.properties)) {
1034 for (const [name, propertySchema] of Object.entries(out.properties)) {
1035 setOwn(properties, name, propertySchema);
1036 }
1037 }
1038 const declaredRequired = new Set(
1039 Array.isArray(out.required) ? out.required.filter(entry => typeof entry === 'string') : []
1040 );
1041 for (const [name, propertySchema] of Object.entries(properties)) {
1042 if (typeof propertySchema === 'boolean') {
1043 unsupported.push({
1044 path: joinPath(path, `properties.${name}`),
1045 keyword: 'properties',
1046 detail: 'boolean subschema',
1047 });
1048 continue;
1049 }
1050 if (declaredRequired.has(name) || !isPlainObject(propertySchema)) continue;
1051 setOwn(properties, name, widenToNullable(propertySchema, acceptsNullInOutput));
1052 recordChange({
1053 path: joinPath(path, `properties.${name}`),
1054 reason: 'optional-property-nullable',
1055 detail: `property "${name}" is now required and accepts null`,
1056 });
1057 }
1058
1059 const acceptsDynamicKeys =
1060 out.additionalProperties === true || isPlainObject(out.additionalProperties);
1061 if (acceptsDynamicKeys) {
1062 unsupported.push({
1063 path,
1064 keyword: 'additionalProperties',
1065 detail: 'object accepts arbitrary keys',
1066 });
1067 } else if (out.patternProperties !== undefined) {
1068 unsupported.push({
1069 path,
1070 keyword: 'patternProperties',
1071 detail: 'object accepts pattern-matched keys',
1072 });
1073 } else if (Object.keys(properties).length === 0 && out.additionalProperties === undefined) {
1074 unsupported.push({
1075 path,
1076 keyword: 'properties',
1077 detail: 'free-form object accepts arbitrary keys',
1078 });
1079 }
1080
1081 return {
1082 ...out,
1083 ...(out.type === undefined ? { type: 'object' } : {}),
1084 properties,
1085 required: Object.keys(properties),
1086 ...(acceptsDynamicKeys ? {} : { additionalProperties: false }),
1087 };
1088 }
1089
1090 const normalized = walk(root, 'schema', 0, '');
1091 if (isPlainObject(normalized)) {
1092 // Wrapping a property in a null branch moves everything nested in it.
1093 for (const { path, ref } of references) {
1094 if (tryResolvePointer(normalized, ref).kind === 'unresolved') {
1095 unsupported.push({
1096 path,
1097 keyword: '$ref',
1098 detail: `$ref "${ref}" target moved by the rewrite`,
1099 });
1100 }
1101 }
1102 }
1103 if (!isPlainObject(normalized) || !isObjectType(normalized.type)) {
1104 unsupported.push({
1105 path: '',
1106 keyword: 'type',
1107 detail: 'root must be a non-nullable object',
1108 });
1109 }
1110
1111 return {
1112 schema: deduplicateJsonSchemaRequiredArrays(normalized) as Record<string, unknown>,
1113 source: root,
1114 changes,
1115 totalChanges,
1116 unsupported,
1117 };
1118 }
1119
1120 /**
1121 * Drops `null`-valued arguments that the tool's own schema does not accept,
1122 * recursively through nested objects and arrays.
1123 *
1124 * Strict structured outputs cannot express optional parameters, so
1125 * {@link toStrictJsonSchema} makes every parameter required and nullable. The
1126 * model then sends `null` for a parameter it would otherwise have omitted;
1127 * forwarding that `null` to the tool would fail validation against the tool's
1128 * real schema, so it is treated as "omitted". A `null` the original schema
1129 * accepts (a nullable field, an explicit "clear this value") is kept.
1130 *
1131 * @param args - Normalized tool arguments.
1132 * @param schema - The dereferenced tool parameter schema the arguments were
1133 * produced for (`StrictJsonSchemaResult.source`).
1134 * @returns A new object; the input is not mutated.
1135 */
1136 export function omitNullToolArguments(
1137 args: Record<string, unknown>,
1138 schema: unknown
1139 ): Record<string, unknown> {
1140 const root: Record<string, unknown> = isPlainObject(schema) ? schema : {};
1141 return omitNulls(args, root, root, 0, createNullCheck(root)) as Record<string, unknown>;
1142 }
1143
1144 /**
1145 * Picks the composition branch that describes a value's shape: the first
1146 * branch with `properties` for an object, the first with `items` for an
1147 * array. Nodes without a composition are returned as they are.
1148 */
1149 function selectBranchFor(
1150 schema: unknown,
1151 value: unknown,
1152 root: Record<string, unknown>
1153 ): Record<string, unknown> | undefined {
1154 const resolved = resolveLocalRefs(schema, root);
1155 if (!isPlainObject(resolved)) return undefined;
1156 const wanted = Array.isArray(value) ? 'items' : 'properties';
1157 const find = (node: unknown, depth: number): Record<string, unknown> | undefined => {
1158 const candidate = resolveLocalRefs(node, root);
1159 if (!isPlainObject(candidate) || depth > MAX_NODE_DEPTH) return undefined;
1160 if (candidate[wanted] !== undefined) return candidate;
1161 for (const keyword of ['anyOf', 'oneOf']) {
1162 const branches = candidate[keyword];
1163 if (!Array.isArray(branches)) continue;
1164 for (const branch of branches) {
1165 const found = find(branch, depth + 1);
1166 if (found) return found;
1167 }
1168 }
1169 return undefined;
1170 };
1171 return find(resolved, 0) ?? resolved;
1172 }
1173
1174 function omitNulls(
1175 value: unknown,
1176 schema: unknown,
1177 root: Record<string, unknown>,
1178 depth: number,
1179 acceptsNull: (schema: unknown) => boolean
1180 ): unknown {
1181 if (depth > MAX_NODE_DEPTH) {
1182 throw new RangeError(`Tool arguments exceed maximum nesting depth of ${MAX_NODE_DEPTH}`);
1183 }
1184 const node = selectBranchFor(schema, value, root);
1185 if (Array.isArray(value)) {
1186 const items = node && isPlainObject(node.items) ? node.items : undefined;
1187 return value.map(item => omitNulls(item, items, root, depth + 1, acceptsNull));
1188 }
1189 if (!isPlainObject(value)) return value;
1190
1191 const properties = node && isPlainObject(node.properties) ? node.properties : {};
1192 const clone: Record<string, unknown> = {};
1193 for (const [key, child] of Object.entries(value)) {
1194 const propertySchema = Object.prototype.hasOwnProperty.call(properties, key)
1195 ? properties[key]
1196 : undefined;
1197 if (child === null) {
1198 if (propertySchema === undefined || acceptsNull(propertySchema)) {
1199 setOwn(clone, key, child);
1200 }
1201 continue;
1202 }
1203 setOwn(clone, key, omitNulls(child, propertySchema, root, depth + 1, acceptsNull));
1204 }
1205 return clone;
1206 }