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 | /** |
| 2 | * JSON-schema property-key sanitization. |
| 3 | * |
| 4 | * Some providers constrain the characters and/or length of tool `input_schema` |
| 5 | * property keys (e.g. Anthropic's Messages API validates every key against |
| 6 | * `^[a-zA-Z0-9_.-]{1,64}$` and rejects the whole `tools` array on a single |
| 7 | * violation). Composio tool schemas can surface keys that break such rules — |
| 8 | * OData parameters like `$top` / `@microsoft.graph.conflictBehavior`, or |
| 9 | * over-long `__`-flattened keys. |
| 10 | * |
| 11 | * This module rewrites offending keys to conforming aliases before the schema is |
| 12 | * sent to the provider, and records a reverse mapping so the original parameter |
| 13 | * names can be restored before a tool call is executed against the Composio |
| 14 | * backend. The *constraint* (which keys are valid and how an illegal key is |
| 15 | * rewritten) is injected as a {@link KeySanitizationPolicy} so the mechanism |
| 16 | * stays provider-agnostic; the traversal, collision handling, reverse mapping, |
| 17 | * prototype safety and depth cap live here. |
| 18 | * |
| 19 | * The reverse mapping mirrors the schema's nesting (object `properties`, array |
| 20 | * `items`/`prefixItems`, and the composition keywords `allOf`/`anyOf`/`oneOf` / |
| 21 | * `not`/`if`/`then`/`else`, whose renames fold into the value level they share) |
| 22 | * rather than being a single flat lookup. This matters because an alias generated |
| 23 | * at one nesting level (e.g. `$top` -> `dollar_top`) must not rewrite a |
| 24 | * legitimately-named `dollar_top` key that happens to exist at a different level. |
| 25 | * Keys nested only under dynamic / `$ref` positions (`additionalProperties`, |
| 26 | * `patternProperties`, `$defs`/`definitions`, `contains`) are still rewritten so |
| 27 | * the provider accepts the schema, but are not restored — see the keyword lists |
| 28 | * below. Dereferencing the schema first (see `dereferenceJsonSchema`) inlines |
| 29 | * `$ref`/`$defs` into restorable value positions, shrinking that residual gap. |
| 30 | * |
| 31 | * @packageDocumentation |
| 32 | * @module utils/schemaPropertyKeys |
| 33 | */ |
| 34 | |
| 35 | import { isPlainObject } from './modifiers/FileToolModifier.utils.neutral'; |
| 36 | |
| 37 | /** Maximum schema nesting we traverse, matching `dereferenceJsonSchema`'s cap. */ |
| 38 | const MAX_SCHEMA_DEPTH = 512; |
| 39 | |
| 40 | /** |
| 41 | * Provider-specific key constraint. The mechanism reserves every already-valid |
| 42 | * sibling key before aliasing, so {@link aliasKey} only needs to produce a |
| 43 | * conforming alias that is distinct from the supplied `taken` set. |
| 44 | */ |
| 45 | export interface KeySanitizationPolicy { |
| 46 | /** Whether a key already conforms to the provider's constraint. */ |
| 47 | isValidKey(key: string): boolean; |
| 48 | /** |
| 49 | * Produce a conforming alias for an illegal `key`, guaranteed distinct from |
| 50 | * every entry in `taken` (the already-assigned keys at the same object level). |
| 51 | */ |
| 52 | aliasKey(key: string, taken: ReadonlySet<string>): string; |
| 53 | } |
| 54 | |
| 55 | /** |
| 56 | * Reverse mapping used to restore original property names at execution time. |
| 57 | * |
| 58 | * It is shaped like the schema it was derived from so restoration is scoped to |
| 59 | * the exact location a rename happened: |
| 60 | * - `renames` — `sanitized -> original` for keys renamed at *this* value level |
| 61 | * (including renames folded in from composition keywords). |
| 62 | * - `children` — restoration mapping for the value under each (sanitized) key, |
| 63 | * keyed by the sanitized key. Only present for children that contain renames. |
| 64 | * - `items` — restoration mapping for array element values. A single mapping |
| 65 | * applies to every element; an array of mappings applies positionally (JSON |
| 66 | * Schema tuple validation / `prefixItems`). Only present when array elements |
| 67 | * contain renames. |
| 68 | * - `restItems` — restoration mapping for array elements *past* a positional |
| 69 | * `items`/`prefixItems` tuple (a 2020-12 single `items` schema sitting next to |
| 70 | * `prefixItems`). Only present when those trailing elements contain renames. |
| 71 | */ |
| 72 | export interface KeyMapping { |
| 73 | renames: Record<string, string>; |
| 74 | children: Record<string, KeyMapping>; |
| 75 | items?: KeyMapping | (KeyMapping | null)[]; |
| 76 | restItems?: KeyMapping; |
| 77 | } |
| 78 | |
| 79 | /** Whether a mapping (or any of its descendants) actually renames a key. */ |
| 80 | export function mappingHasRenames(mapping: KeyMapping): boolean { |
| 81 | // `children` and `items` are only populated when they carry renames (see |
| 82 | // `sanitizeNode`), so this stays a shallow check. |
| 83 | return ( |
| 84 | Object.keys(mapping.renames).length > 0 || |
| 85 | Object.keys(mapping.children).length > 0 || |
| 86 | mapping.items != null || |
| 87 | mapping.restItems != null |
| 88 | ); |
| 89 | } |
| 90 | |
| 91 | /** |
| 92 | * Composition/applicator keywords whose sub-schema(s) constrain the *same* value |
| 93 | * as the parent. Property-key renames generated inside them are merged into the |
| 94 | * parent's value level, because the value carries no extra nesting for these |
| 95 | * keywords. `not`/`if`/`then`/`else` hold a single sub-schema; `allOf`/`anyOf`/ |
| 96 | * `oneOf` hold an array of sub-schemas. |
| 97 | */ |
| 98 | const COMPOSITION_SINGLE_KEYWORDS = ['not', 'if', 'then', 'else'] as const; |
| 99 | const COMPOSITION_LIST_KEYWORDS = ['allOf', 'anyOf', 'oneOf'] as const; |
| 100 | |
| 101 | /** |
| 102 | * Positions whose nested keys are rewritten so the provider accepts the schema, |
| 103 | * but which we cannot tie to a concrete value position for restoration: dynamic |
| 104 | * keys (`additionalProperties`, `patternProperties`) and `$ref` targets (`$defs`/ |
| 105 | * `definitions`, unresolved unless the caller dereferences first), plus |
| 106 | * `contains`. A value filled via an alias generated here reaches the backend |
| 107 | * un-restored — strictly better than the whole `tools` array being rejected. |
| 108 | */ |
| 109 | const REWRITE_ONLY_SINGLE_KEYWORDS = ['additionalProperties', 'contains'] as const; |
| 110 | const REWRITE_ONLY_MAP_KEYWORDS = ['patternProperties', '$defs', 'definitions'] as const; |
| 111 | |
| 112 | /** |
| 113 | * Sanitizes a single sub-schema. Returns the rewritten node and its mapping, or |
| 114 | * a `null` mapping when nothing inside it was renamed (keeps mappings sparse). |
| 115 | */ |
| 116 | function sanitizeSubschema( |
| 117 | value: unknown, |
| 118 | policy: KeySanitizationPolicy, |
| 119 | depth: number |
| 120 | ): { node: unknown; mapping: KeyMapping | null } { |
| 121 | if (!isPlainObject(value)) { |
| 122 | return { node: value, mapping: null }; |
| 123 | } |
| 124 | const { node, mapping } = sanitizeNode(value, policy, depth + 1); |
| 125 | return { node, mapping: mappingHasRenames(mapping) ? mapping : null }; |
| 126 | } |
| 127 | |
| 128 | /** Sanitizes an array of positional sub-schemas (tuple `items` / `prefixItems`). */ |
| 129 | function sanitizeTuple( |
| 130 | entries: unknown[], |
| 131 | policy: KeySanitizationPolicy, |
| 132 | depth: number |
| 133 | ): { nodes: unknown[]; mappings: (KeyMapping | null)[] | undefined } { |
| 134 | const nodes: unknown[] = []; |
| 135 | const mappings: (KeyMapping | null)[] = []; |
| 136 | let anyRenamed = false; |
| 137 | for (const entry of entries) { |
| 138 | const { node, mapping } = sanitizeSubschema(entry, policy, depth); |
| 139 | nodes.push(node); |
| 140 | mappings.push(mapping); |
| 141 | if (mapping) anyRenamed = true; |
| 142 | } |
| 143 | return { nodes, mappings: anyRenamed ? mappings : undefined }; |
| 144 | } |
| 145 | |
| 146 | /** |
| 147 | * Rewrites the nested keys of a `{ name -> sub-schema }` map (e.g. `$defs`, |
| 148 | * `patternProperties`). The map's own keys are names/patterns, not value |
| 149 | * property keys, so they are left untouched and no restoration mapping is kept. |
| 150 | */ |
| 151 | function sanitizeSchemaMap( |
| 152 | map: Record<string, unknown>, |
| 153 | policy: KeySanitizationPolicy, |
| 154 | depth: number |
| 155 | ): Record<string, unknown> { |
| 156 | const out: Record<string, unknown> = Object.create(null); |
| 157 | for (const [key, value] of Object.entries(map)) { |
| 158 | out[key] = sanitizeSubschema(value, policy, depth).node; |
| 159 | } |
| 160 | return out; |
| 161 | } |
| 162 | |
| 163 | /** |
| 164 | * Merges `source`'s renames into `target`, both describing the same value level |
| 165 | * (used to fold composition branches into their parent). `target` wins on |
| 166 | * conflict, since it is the more direct (`properties`-level) mapping. |
| 167 | * |
| 168 | * Known limitation: folding sibling `allOf`/`anyOf`/`oneOf` branches into one |
| 169 | * value level is lossy when two branches disagree on an alias. If branch A aliases |
| 170 | * an illegal key to `X` while branch B has a distinct illegal key that also aliases |
| 171 | * to `X` — or a *legitimate* property literally named `X` — only the first-seen |
| 172 | * entry survives, so an argument that satisfied the other branch restores to the |
| 173 | * wrong original name. Which branch a runtime value matched can't be recovered from |
| 174 | * the value alone (that needs full schema evaluation against the value), so these |
| 175 | * cross-branch collisions stay effectively rewrite-only — still strictly better |
| 176 | * than the whole `tools` array being rejected. They are rare in practice. |
| 177 | */ |
| 178 | function mergeMappingInto(target: KeyMapping, source: KeyMapping): void { |
| 179 | for (const [alias, original] of Object.entries(source.renames)) { |
| 180 | if (!(alias in target.renames)) { |
| 181 | target.renames[alias] = original; |
| 182 | } |
| 183 | } |
| 184 | for (const [key, childSource] of Object.entries(source.children)) { |
| 185 | const existing = target.children[key]; |
| 186 | if (existing) { |
| 187 | mergeMappingInto(existing, childSource); |
| 188 | } else { |
| 189 | target.children[key] = childSource; |
| 190 | } |
| 191 | } |
| 192 | if (target.items === undefined && source.items !== undefined) { |
| 193 | target.items = source.items; |
| 194 | if (source.restItems !== undefined) { |
| 195 | target.restItems = source.restItems; |
| 196 | } |
| 197 | } |
| 198 | } |
| 199 | |
| 200 | /** |
| 201 | * Recursively sanitizes the property keys of a JSON-schema node, returning the |
| 202 | * rewritten node and a {@link KeyMapping} shaped like the node. Traversal covers |
| 203 | * object `properties`, array `items`/`prefixItems`, the composition keywords |
| 204 | * (`allOf`/`anyOf`/`oneOf`, `not`/`if`/`then`/`else` — whose renames merge into |
| 205 | * this level), and the rewrite-only positions in {@link REWRITE_ONLY_SINGLE_KEYWORDS} |
| 206 | * / {@link REWRITE_ONLY_MAP_KEYWORDS}. |
| 207 | * |
| 208 | * The input node is never mutated; a new node is returned. |
| 209 | */ |
| 210 | function sanitizeNode( |
| 211 | node: Record<string, unknown>, |
| 212 | policy: KeySanitizationPolicy, |
| 213 | depth = 0 |
| 214 | ): { |
| 215 | node: Record<string, unknown>; |
| 216 | mapping: KeyMapping; |
| 217 | } { |
| 218 | if (depth >= MAX_SCHEMA_DEPTH) { |
| 219 | throw new Error( |
| 220 | `Tool schema nesting exceeded the maximum supported depth (${MAX_SCHEMA_DEPTH})` |
| 221 | ); |
| 222 | } |
| 223 | |
| 224 | const result: Record<string, unknown> = { ...node }; |
| 225 | // Lookup/result tables are prototype-free so a property key that collides with |
| 226 | // an `Object.prototype` member (`__proto__`, `constructor`, `toString`, …) |
| 227 | // becomes a plain own entry instead of resolving to (or reparenting via) the |
| 228 | // inherited member. Mirrors the `POLLUTING_KEYS` defense in `jsonSchema.ts`. |
| 229 | const renames: Record<string, string> = Object.create(null); |
| 230 | const children: Record<string, KeyMapping> = Object.create(null); |
| 231 | const mapping: KeyMapping = { renames, children }; |
| 232 | |
| 233 | const properties = node.properties; |
| 234 | if (isPlainObject(properties)) { |
| 235 | const newProperties: Record<string, unknown> = Object.create(null); |
| 236 | const renamedOriginalToSanitized: Record<string, string> = Object.create(null); |
| 237 | |
| 238 | // Reserve all already-valid keys up front so they keep their exact names and |
| 239 | // sanitized aliases are generated around them (a valid `dollar_top` must not |
| 240 | // be clobbered by a sanitized `$top`). |
| 241 | const taken = new Set<string>(); |
| 242 | for (const key of Object.keys(properties)) { |
| 243 | if (policy.isValidKey(key)) { |
| 244 | taken.add(key); |
| 245 | } |
| 246 | } |
| 247 | |
| 248 | for (const [key, rawValue] of Object.entries(properties)) { |
| 249 | const safeKey = policy.isValidKey(key) ? key : policy.aliasKey(key, taken); |
| 250 | taken.add(safeKey); |
| 251 | |
| 252 | const { node: childNode, mapping: childMapping } = sanitizeSubschema(rawValue, policy, depth); |
| 253 | newProperties[safeKey] = childNode; |
| 254 | if (childMapping) { |
| 255 | children[safeKey] = childMapping; |
| 256 | } |
| 257 | |
| 258 | if (safeKey !== key) { |
| 259 | renames[safeKey] = key; |
| 260 | renamedOriginalToSanitized[key] = safeKey; |
| 261 | } |
| 262 | } |
| 263 | |
| 264 | result.properties = newProperties; |
| 265 | |
| 266 | // Keep `required` in sync with the renamed keys at this level. |
| 267 | if (Array.isArray(node.required)) { |
| 268 | result.required = node.required.map(name => |
| 269 | typeof name === 'string' && renamedOriginalToSanitized[name] |
| 270 | ? renamedOriginalToSanitized[name] |
| 271 | : name |
| 272 | ); |
| 273 | } |
| 274 | } |
| 275 | |
| 276 | // Array element schemas come from up to two positional sources — a Draft-7 |
| 277 | // `items` tuple and the 2020-12 `prefixItems` tuple — plus one "applies to every |
| 278 | // element" source, a single `items` schema. When `prefixItems` provides the |
| 279 | // positional mapping, a sibling single `items` schema constrains the elements |
| 280 | // *past* the tuple (2020-12 semantics); its renames are kept separately as |
| 281 | // `restItems` so those tail elements restore too instead of being dropped (or |
| 282 | // the rest mapping bleeding onto the tuple positions). Restoration reaches array |
| 283 | // elements through `mapping.items`/`mapping.restItems` — a `properties`-only walk |
| 284 | // would let illegal keys nested in elements through and still be rejected. |
| 285 | const itemsSchema = node.items; |
| 286 | let positionalItems: (KeyMapping | null)[] | undefined; |
| 287 | let uniformItems: KeyMapping | undefined; |
| 288 | if (isPlainObject(itemsSchema)) { |
| 289 | const { node: childNode, mapping: childMapping } = sanitizeSubschema( |
| 290 | itemsSchema, |
| 291 | policy, |
| 292 | depth |
| 293 | ); |
| 294 | result.items = childNode; |
| 295 | if (childMapping) { |
| 296 | uniformItems = childMapping; |
| 297 | } |
| 298 | } else if (Array.isArray(itemsSchema)) { |
| 299 | const { nodes, mappings } = sanitizeTuple(itemsSchema, policy, depth); |
| 300 | result.items = nodes; |
| 301 | positionalItems = mappings; |
| 302 | } |
| 303 | if (Array.isArray(node.prefixItems)) { |
| 304 | const { nodes, mappings } = sanitizeTuple(node.prefixItems, policy, depth); |
| 305 | result.prefixItems = nodes; |
| 306 | // `prefixItems` is the 2020-12 positional keyword; use it for the positional |
| 307 | // mapping when a Draft-7 `items` tuple didn't already provide one. |
| 308 | if (positionalItems === undefined) { |
| 309 | positionalItems = mappings; |
| 310 | } |
| 311 | } |
| 312 | if (positionalItems) { |
| 313 | mapping.items = positionalItems; |
| 314 | // A single `items` schema sitting next to a `prefixItems` tuple describes the |
| 315 | // elements after the tuple; keep its mapping so they restore positionally. |
| 316 | if (uniformItems && Array.isArray(node.prefixItems)) { |
| 317 | mapping.restItems = uniformItems; |
| 318 | } |
| 319 | } else if (uniformItems) { |
| 320 | mapping.items = uniformItems; |
| 321 | } |
| 322 | |
| 323 | // Composition keywords constrain the *same* value, so renames generated inside |
| 324 | // them are merged into this level (the value has no extra nesting for them). |
| 325 | for (const keyword of COMPOSITION_SINGLE_KEYWORDS) { |
| 326 | const sub = node[keyword]; |
| 327 | if (isPlainObject(sub)) { |
| 328 | const { node: childNode, mapping: childMapping } = sanitizeSubschema(sub, policy, depth); |
| 329 | result[keyword] = childNode; |
| 330 | if (childMapping) { |
| 331 | mergeMappingInto(mapping, childMapping); |
| 332 | } |
| 333 | } |
| 334 | } |
| 335 | for (const keyword of COMPOSITION_LIST_KEYWORDS) { |
| 336 | const list = node[keyword]; |
| 337 | if (Array.isArray(list)) { |
| 338 | result[keyword] = list.map(entry => { |
| 339 | const { node: childNode, mapping: childMapping } = sanitizeSubschema(entry, policy, depth); |
| 340 | if (childMapping) { |
| 341 | mergeMappingInto(mapping, childMapping); |
| 342 | } |
| 343 | return childNode; |
| 344 | }); |
| 345 | } |
| 346 | } |
| 347 | |
| 348 | // Rewrite-only positions: keys are made compliant, but no restoration mapping |
| 349 | // is kept (see the keyword lists above for why). |
| 350 | for (const keyword of REWRITE_ONLY_SINGLE_KEYWORDS) { |
| 351 | const sub = node[keyword]; |
| 352 | if (isPlainObject(sub)) { |
| 353 | result[keyword] = sanitizeSubschema(sub, policy, depth).node; |
| 354 | } |
| 355 | } |
| 356 | for (const keyword of REWRITE_ONLY_MAP_KEYWORDS) { |
| 357 | const sub = node[keyword]; |
| 358 | if (isPlainObject(sub)) { |
| 359 | result[keyword] = sanitizeSchemaMap(sub, policy, depth); |
| 360 | } |
| 361 | } |
| 362 | |
| 363 | return { node: result, mapping }; |
| 364 | } |
| 365 | |
| 366 | /** |
| 367 | * Sanitizes a tool `input_schema` so all property keys conform to `policy`. |
| 368 | * |
| 369 | * @param schema - The tool input schema to sanitize. |
| 370 | * @param policy - Provider constraint describing valid keys and how to rewrite |
| 371 | * illegal ones. |
| 372 | * @returns The sanitized schema (a copy) and a {@link KeyMapping} for restoring |
| 373 | * the original keys. Use {@link mappingHasRenames} to tell whether |
| 374 | * anything was rewritten. |
| 375 | */ |
| 376 | export function sanitizeSchemaPropertyKeys<T extends Record<string, unknown>>( |
| 377 | schema: T, |
| 378 | policy: KeySanitizationPolicy |
| 379 | ): { schema: T; mapping: KeyMapping } { |
| 380 | const { node, mapping } = sanitizeNode(schema, policy); |
| 381 | return { schema: node as T, mapping }; |
| 382 | } |
| 383 | |
| 384 | /** |
| 385 | * Restores original property names in a tool-call argument object using the |
| 386 | * mapping produced by {@link sanitizeSchemaPropertyKeys}. The mapping is walked |
| 387 | * in lockstep with the value, so a key is only renamed at the nesting level where |
| 388 | * its alias was actually generated. Nested objects and arrays are handled |
| 389 | * recursively. Returns a new value; the input is not mutated. |
| 390 | */ |
| 391 | export function restoreOriginalKeys(value: unknown, mapping: KeyMapping, depth = 0): unknown { |
| 392 | if (depth >= MAX_SCHEMA_DEPTH) { |
| 393 | throw new Error( |
| 394 | `Tool arguments nesting exceeded the maximum supported depth (${MAX_SCHEMA_DEPTH})` |
| 395 | ); |
| 396 | } |
| 397 | |
| 398 | if (Array.isArray(value)) { |
| 399 | const { items, restItems } = mapping; |
| 400 | if (Array.isArray(items)) { |
| 401 | return value.map((item, index) => { |
| 402 | // Elements inside the tuple use their positional mapping; elements past it |
| 403 | // use the trailing single-`items` rest mapping (2020-12), if any. |
| 404 | const itemMapping = index < items.length ? items[index] : restItems; |
| 405 | return itemMapping ? restoreOriginalKeys(item, itemMapping, depth + 1) : item; |
| 406 | }); |
| 407 | } |
| 408 | if (items) { |
| 409 | return value.map(item => restoreOriginalKeys(item, items, depth + 1)); |
| 410 | } |
| 411 | return value; |
| 412 | } |
| 413 | |
| 414 | if (isPlainObject(value)) { |
| 415 | // Prototype-free so a model-supplied key equal to an `Object.prototype` |
| 416 | // member name (`__proto__`, `constructor`, …) is written as a plain own |
| 417 | // property rather than reparenting the result or hitting an inherited member. |
| 418 | const restored: Record<string, unknown> = Object.create(null); |
| 419 | for (const [key, val] of Object.entries(value)) { |
| 420 | // `renames`/`children` are themselves prototype-free (see `sanitizeNode`), |
| 421 | // so these lookups return `undefined` for non-own keys instead of an |
| 422 | // inherited function — no spurious rename and no crash on recursion. |
| 423 | const originalKey = mapping.renames[key] ?? key; |
| 424 | const childMapping = mapping.children[key]; |
| 425 | restored[originalKey] = childMapping |
| 426 | ? restoreOriginalKeys(val, childMapping, depth + 1) |
| 427 | : val; |
| 428 | } |
| 429 | return restored; |
| 430 | } |
| 431 | |
| 432 | return value; |
| 433 | } |