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 333 lines 11.4 KB
Raw
1 import type { JSONSchemaProperty } from '../../types/tool.types';
2
3 // Helper function to recognise plain objects
4 export function isPlainObject(val: unknown): val is Record<string, unknown> {
5 return typeof val === 'object' && val !== null && !Array.isArray(val);
6 }
7
8 /**
9 * Transforms a single JSON schema property, recursively handling nested properties,
10 * anyOf, oneOf, and allOf.
11 */
12 const transformSchema = (property: JSONSchemaProperty): JSONSchemaProperty => {
13 if (property.file_uploadable) {
14 // Transform file-uploadable property
15 return {
16 title: property.title,
17 description: property.description,
18 format: 'path',
19 type: 'string',
20 file_uploadable: true,
21 };
22 }
23
24 const newProperty = { ...property };
25
26 if (property.type === 'object' && property.properties) {
27 // Recursively transform nested properties
28 newProperty.properties = transformProperties(property.properties);
29 }
30
31 if (property.anyOf) {
32 newProperty.anyOf = property.anyOf.map(transformSchema);
33 }
34
35 if (property.oneOf) {
36 newProperty.oneOf = property.oneOf.map(transformSchema);
37 }
38
39 if (property.allOf) {
40 newProperty.allOf = property.allOf.map(transformSchema);
41 }
42
43 if (property.items) {
44 if (Array.isArray(property.items)) {
45 newProperty.items = property.items.map(transformSchema);
46 } else {
47 newProperty.items = transformSchema(property.items);
48 }
49 }
50
51 return newProperty;
52 };
53
54 /**
55 * Transforms the properties of the tool schema to include the file upload URL.
56 *
57 * Attaches the format: 'path' to the properties that are file uploadable for agents.
58 *
59 * @param properties - The properties of the tool schema.
60 * @returns The transformed properties.
61 */
62 export const transformProperties = (
63 properties: Record<string, JSONSchemaProperty>
64 ): Record<string, JSONSchemaProperty> => {
65 const newProperties: Record<string, JSONSchemaProperty> = {};
66
67 for (const [key, property] of Object.entries(properties)) {
68 newProperties[key] = transformSchema(property);
69 }
70
71 return newProperties;
72 };
73
74 /**
75 * Recursively checks if a schema (or any of its variants) contains a specific file property.
76 */
77 export const schemaHasFileProperty = (
78 schema: JSONSchemaProperty | undefined,
79 property: 'file_uploadable' | 'file_downloadable'
80 ): boolean => {
81 if (!schema) return false;
82 if (schema[property]) return true;
83
84 // Check nested properties
85 if (schema.properties) {
86 for (const prop of Object.values(schema.properties)) {
87 if (schemaHasFileProperty(prop, property)) return true;
88 }
89 }
90
91 // Check anyOf/oneOf/allOf variants
92 if (schema.anyOf) {
93 for (const variant of schema.anyOf) {
94 if (schemaHasFileProperty(variant, property)) return true;
95 }
96 }
97 if (schema.oneOf) {
98 for (const variant of schema.oneOf) {
99 if (schemaHasFileProperty(variant, property)) return true;
100 }
101 }
102 if (schema.allOf) {
103 for (const variant of schema.allOf) {
104 if (schemaHasFileProperty(variant, property)) return true;
105 }
106 }
107
108 // Check array items
109 if (schema.items) {
110 if (Array.isArray(schema.items)) {
111 for (const item of schema.items) {
112 if (schemaHasFileProperty(item, property)) return true;
113 }
114 } else {
115 if (schemaHasFileProperty(schema.items, property)) return true;
116 }
117 }
118
119 // Check `$ref` targets. Composio toolkits routinely express file flags
120 // through a `$ref`/`$defs` indirection (e.g. GMAIL_GET_ATTACHMENT), and
121 // this predicate is the cheap gate that decides whether a schema is worth
122 // dereferencing at all — without this it answers `false` for every
123 // ref-based schema. Callers walk the *dereferenced* schema, where
124 // `dereferenceJsonSchema` has already stripped these blocks, so an unused
125 // `$defs` entry can only cost a redundant walk, never a wrong upload.
126 for (const definitions of [schema.$defs, schema.definitions]) {
127 if (!definitions) continue;
128 for (const definition of Object.values(definitions)) {
129 if (schemaHasFileProperty(definition, property)) return true;
130 }
131 }
132
133 return false;
134 };
135
136 /**
137 * Recursively checks if a schema (or any of its variants) contains file_uploadable properties.
138 */
139 export const schemaHasFileUploadable = (schema: JSONSchemaProperty | undefined): boolean => {
140 return schemaHasFileProperty(schema, 'file_uploadable');
141 };
142
143 /**
144 * Recursively checks if a schema (or any of its variants) contains file_downloadable properties.
145 */
146 export const schemaHasFileDownloadable = (schema: JSONSchemaProperty | undefined): boolean => {
147 return schemaHasFileProperty(schema, 'file_downloadable');
148 };
149
150 /**
151 * Sentinel a leaf handler returns to have {@link walkFileUploadableLeaves}
152 * omit that key/item from its parent container. `''` and `null` are legal
153 * payload values, so neither can double as "remove this".
154 */
155 export const DELETE_VALUE: unique symbol = Symbol('composio.delete-value');
156
157 /**
158 * `''` at a `file_uploadable` leaf means "no file": it is never a staged
159 * `{ name, mimetype, s3key }` descriptor, so the backend rejects it with a
160 * validation error, while callers (and the playground UI) mean "absent". The
161 * walker omits the key instead. `null` is left alone — schemas with a `null`
162 * variant accept it, and the backend reports the mismatch otherwise.
163 */
164 export const isEmptyFileValue = (value: unknown): boolean => value === '';
165
166 export const getSchemaVariants = (schema: JSONSchemaProperty | undefined): JSONSchemaProperty[] => [
167 ...(schema?.anyOf ?? []),
168 ...(schema?.oneOf ?? []),
169 ...(schema?.allOf ?? []),
170 ];
171
172 /** Best-effort runtime shape match for selecting composed schema variants. */
173 export const jsonSchemaTypeMatchesValue = (schema: JSONSchemaProperty, value: unknown): boolean => {
174 const schemaType = schema.type;
175
176 if (Array.isArray(schemaType)) {
177 return schemaType.some(type => jsonSchemaTypeMatchesValue({ ...schema, type }, value));
178 }
179
180 if (schemaType === undefined) {
181 if (schema.properties) return isPlainObject(value);
182 if (schema.items) return Array.isArray(value);
183 return false;
184 }
185
186 switch (schemaType) {
187 case 'array':
188 return Array.isArray(value);
189 case 'object':
190 return isPlainObject(value);
191 case 'string':
192 return typeof value === 'string';
193 case 'integer':
194 return Number.isInteger(value);
195 case 'number':
196 return typeof value === 'number';
197 case 'boolean':
198 return typeof value === 'boolean';
199 case 'null':
200 return value === null;
201 default:
202 return false;
203 }
204 };
205
206 /** Mirrors the array-shape inference used by {@link jsonSchemaTypeMatchesValue}. */
207 const isArrayShapedSchema = (schema: JSONSchemaProperty | undefined): boolean => {
208 if (!schema) return false;
209 if (Array.isArray(schema.type)) return schema.type.includes('array');
210 return schema.type === 'array' || (schema.type === undefined && schema.items !== undefined);
211 };
212
213 /** Mirrors the object-shape inference used by {@link jsonSchemaTypeMatchesValue}. */
214 const isObjectShapedSchema = (schema: JSONSchemaProperty | undefined): boolean => {
215 if (!schema) return false;
216 if (Array.isArray(schema.type)) return schema.type.includes('object');
217 return schema.type === 'object' || (schema.type === undefined && schema.properties !== undefined);
218 };
219
220 /**
221 * Picks the file-bearing `anyOf`/`oneOf`/`allOf` variant whose JSON Schema
222 * shape matches the runtime value, falling back to the first file-bearing
223 * variant to preserve historical behavior.
224 */
225 export const findSchemaVariantWithFileProperty = (
226 schema: JSONSchemaProperty | undefined,
227 property: 'file_uploadable' | 'file_downloadable',
228 value: unknown
229 ): JSONSchemaProperty | undefined => {
230 const candidates = getSchemaVariants(schema).filter(variant =>
231 schemaHasFileProperty(variant, property)
232 );
233
234 return (
235 candidates.find(candidate => jsonSchemaTypeMatchesValue(candidate, value)) ?? candidates[0]
236 );
237 };
238
239 /**
240 * Recursively walks a runtime value alongside its (already dereferenced)
241 * JSON-Schema node and passes every value sitting at a `file_uploadable`
242 * node through `leaf`. A leaf returning {@link DELETE_VALUE} is omitted from
243 * its parent object/array. Returns a **new** value; nothing is mutated.
244 *
245 * Composed schemas are resolved to the single file-bearing variant whose
246 * shape matches the value: with `oneOf`, exactly one variant should apply at
247 * runtime, and applying several would stage the same file once per variant.
248 */
249 export const walkFileUploadableLeaves = async (
250 value: unknown,
251 schema: JSONSchemaProperty | undefined,
252 leaf: (value: unknown) => Promise<unknown>
253 ): Promise<unknown> => {
254 if (schema?.file_uploadable) {
255 return leaf(value);
256 }
257
258 const uploadableVariant = findSchemaVariantWithFileProperty(schema, 'file_uploadable', value);
259 if (uploadableVariant) {
260 // A scalar empty string cannot match an array-only file input, but callers
261 // use it to mean "no files". Route it through the leaf handler so it is
262 // omitted, unless another non-file variant explicitly accepts strings.
263 const matchingNonFileVariant = getSchemaVariants(schema).some(
264 variant =>
265 !schemaHasFileProperty(variant, 'file_uploadable') &&
266 jsonSchemaTypeMatchesValue(variant, value)
267 );
268 if (
269 isEmptyFileValue(value) &&
270 isArrayShapedSchema(uploadableVariant) &&
271 !matchingNonFileVariant
272 ) {
273 return leaf(value);
274 }
275 return walkFileUploadableLeaves(value, uploadableVariant, leaf);
276 }
277
278 if (
279 isEmptyFileValue(value) &&
280 isArrayShapedSchema(schema) &&
281 schemaHasFileProperty(schema, 'file_uploadable')
282 ) {
283 return leaf(value);
284 }
285
286 if (isObjectShapedSchema(schema) && schema?.properties && isPlainObject(value)) {
287 const transformed: Record<string, unknown> = {};
288 for (const [k, v] of Object.entries(value)) {
289 const propertySchema = Object.hasOwn(schema.properties, k) ? schema.properties[k] : undefined;
290 const walked = await walkFileUploadableLeaves(v, propertySchema, leaf);
291 if (walked !== DELETE_VALUE) {
292 // Define every key as an own data property so reserved JSON keys such
293 // as `__proto__` remain enumerable without invoking its inherited
294 // setter and changing this ordinary object's prototype.
295 Object.defineProperty(transformed, k, {
296 configurable: true,
297 enumerable: true,
298 value: walked,
299 writable: true,
300 });
301 }
302 }
303 return transformed;
304 }
305
306 if (isArrayShapedSchema(schema) && schema?.items && Array.isArray(value)) {
307 // `items` can be a single schema or an array of schemas; we handle both.
308 const itemSchema = Array.isArray(schema.items) ? schema.items[0] : schema.items;
309 const walked = await Promise.all(
310 value.map(item => walkFileUploadableLeaves(item, itemSchema as JSONSchemaProperty, leaf))
311 );
312 return walked.filter(item => item !== DELETE_VALUE);
313 }
314
315 return value;
316 };
317
318 /**
319 * Omits `''` at `file_uploadable` leaves of `args` without uploading
320 * anything. This is the schema-aware half of the upload modifier that needs
321 * no filesystem access, so it also runs when automatic upload is disabled:
322 * an empty file value is never a valid staged descriptor and the backend
323 * would reject it (https://github.com/ComposioHQ/composio/issues/4233).
324 * Any other value — a local path, a staged descriptor, a list — is
325 * forwarded untouched.
326 */
327 export const dropEmptyFileUploads = (
328 args: Record<string, unknown>,
329 schema: JSONSchemaProperty | undefined
330 ): Promise<unknown> =>
331 walkFileUploadableLeaves(args, schema, async value =>
332 isEmptyFileValue(value) ? DELETE_VALUE : value
333 );