Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 | } |