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 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 | ); |