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
+}