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

next
ts 433 lines 17.8 KB
Raw
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 }