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 { |
| 2 | Tool, |
| 3 | ToolExecuteParams, |
| 4 | ToolExecuteResponse, |
| 5 | JSONSchemaProperty, |
| 6 | } from '../../types/tool.types'; |
| 7 | import ComposioClient from '@composio/client'; |
| 8 | import logger from '../logger'; |
| 9 | import { |
| 10 | ComposioFileNotFoundError, |
| 11 | ComposioFileUploadAbortedError, |
| 12 | ComposioFileUploadError, |
| 13 | ComposioFileUploadPathNotAllowedError, |
| 14 | ComposioSensitiveFilePathBlockedError, |
| 15 | } from '../../errors/FileModifierErrors'; |
| 16 | import { ComposioRequestCancelledError } from '../../errors/SDKErrors'; |
| 17 | import type { beforeFileUploadModifier } from '../../types/modifiers.types'; |
| 18 | import { |
| 19 | downloadFileFromS3, |
| 20 | getFileDataAfterUploadingToS3, |
| 21 | isHttpUrl, |
| 22 | type GetFileDataAfterUploadingToS3Options, |
| 23 | } from '../fileUtils.node'; |
| 24 | import { |
| 25 | DELETE_VALUE, |
| 26 | findSchemaVariantWithFileProperty, |
| 27 | getSchemaVariants, |
| 28 | isEmptyFileValue, |
| 29 | isPlainObject, |
| 30 | transformProperties, |
| 31 | walkFileUploadableLeaves, |
| 32 | } from './FileToolModifier.utils.neutral'; |
| 33 | import { dereferenceJsonSchema } from '../jsonSchema'; |
| 34 | import { withCancellation } from '../cancellation'; |
| 35 | |
| 36 | /** |
| 37 | * Inlines internal `$ref` pointers so the file walkers below can see the |
| 38 | * `file_uploadable` / `file_downloadable` flags that live behind a |
| 39 | * `$ref`/`$defs` indirection (e.g. `GMAIL_GET_ATTACHMENT`). The walkers only |
| 40 | * recurse `properties`/`anyOf`/`oneOf`/`allOf`/`items` and never dereference, |
| 41 | * so without this a flagged field reachable only through a `$ref` is silently |
| 42 | * missed — the file is never staged/downloaded. `'sentinel'` mode keeps tools |
| 43 | * whose schema omits the `$defs` target working (see |
| 44 | * https://github.com/ComposioHQ/composio/issues/3307) instead of throwing. |
| 45 | */ |
| 46 | const resolveFileSchema = <Schema extends JSONSchemaProperty>( |
| 47 | schema: Schema | undefined |
| 48 | ): Schema | undefined => |
| 49 | schema ? dereferenceJsonSchema(schema, { onUnresolved: 'sentinel' }) : schema; |
| 50 | |
| 51 | /** |
| 52 | * Stages one `file_uploadable` leaf: a local path / URL string or a `File` |
| 53 | * is uploaded to S3 and replaced by its `{ name, mimetype, s3key }` |
| 54 | * descriptor; `''` means "no file" and is dropped from the request; |
| 55 | * anything else (e.g. an already-staged descriptor) passes through. |
| 56 | */ |
| 57 | const stageFileValue = async ( |
| 58 | value: unknown, |
| 59 | ctx: { |
| 60 | toolSlug: string; |
| 61 | toolkitSlug: string; |
| 62 | client: ComposioClient; |
| 63 | } & Pick< |
| 64 | GetFileDataAfterUploadingToS3Options, |
| 65 | | 'sensitiveFileUploadProtection' |
| 66 | | 'fileUploadPathDenySegments' |
| 67 | | 'fileUploadAllowlist' |
| 68 | | 'signal' |
| 69 | > & { |
| 70 | beforeFileUpload?: beforeFileUploadModifier; |
| 71 | } |
| 72 | ): Promise<unknown> => { |
| 73 | if (isEmptyFileValue(value)) return DELETE_VALUE; |
| 74 | // Upload only if the runtime value is a string (i.e., a local path) or blob |
| 75 | if (typeof value !== 'string' && !(value instanceof File)) return value; |
| 76 | |
| 77 | const runBeforeFileUpload = async ( |
| 78 | path: string, |
| 79 | source: 'path' | 'url' | 'file' |
| 80 | ): Promise<string> => { |
| 81 | if (!ctx.beforeFileUpload) { |
| 82 | return path; |
| 83 | } |
| 84 | const out = await ctx.beforeFileUpload({ |
| 85 | path, |
| 86 | source, |
| 87 | toolSlug: ctx.toolSlug, |
| 88 | toolkitSlug: ctx.toolkitSlug, |
| 89 | }); |
| 90 | if (out === false) { |
| 91 | throw new ComposioFileUploadAbortedError( |
| 92 | 'File upload was aborted because beforeFileUpload returned false.' |
| 93 | ); |
| 94 | } |
| 95 | return out; |
| 96 | }; |
| 97 | |
| 98 | if (typeof value === 'string') { |
| 99 | // Match the URL/local-path split used downstream in |
| 100 | // getFileDataAfterUploadingToS3 so the hook sees the same categorisation. |
| 101 | const source = isHttpUrl(value) ? 'url' : 'path'; |
| 102 | const pathOrUrl = await runBeforeFileUpload(value, source); |
| 103 | logger.debug(`Uploading file "${pathOrUrl}"`); |
| 104 | return getFileDataAfterUploadingToS3(pathOrUrl, { |
| 105 | toolSlug: ctx.toolSlug, |
| 106 | toolkitSlug: ctx.toolkitSlug, |
| 107 | client: ctx.client, |
| 108 | sensitiveFileUploadProtection: ctx.sensitiveFileUploadProtection, |
| 109 | fileUploadPathDenySegments: ctx.fileUploadPathDenySegments, |
| 110 | fileUploadAllowlist: ctx.fileUploadAllowlist, |
| 111 | signal: ctx.signal, |
| 112 | }); |
| 113 | } |
| 114 | |
| 115 | // File — `path` is the filename only; a string return replaces it with a |
| 116 | // local-path upload. |
| 117 | if (ctx.beforeFileUpload) { |
| 118 | const out = await ctx.beforeFileUpload({ |
| 119 | path: value.name, |
| 120 | source: 'file', |
| 121 | toolSlug: ctx.toolSlug, |
| 122 | toolkitSlug: ctx.toolkitSlug, |
| 123 | }); |
| 124 | if (out === false) { |
| 125 | throw new ComposioFileUploadAbortedError( |
| 126 | 'File upload was aborted because beforeFileUpload returned false.' |
| 127 | ); |
| 128 | } |
| 129 | if (typeof out === 'string' && out !== value.name) { |
| 130 | logger.debug(`Uploading file from path "${out}" (replaced File: ${value.name})`); |
| 131 | return getFileDataAfterUploadingToS3(out, { |
| 132 | toolSlug: ctx.toolSlug, |
| 133 | toolkitSlug: ctx.toolkitSlug, |
| 134 | client: ctx.client, |
| 135 | sensitiveFileUploadProtection: ctx.sensitiveFileUploadProtection, |
| 136 | fileUploadPathDenySegments: ctx.fileUploadPathDenySegments, |
| 137 | fileUploadAllowlist: ctx.fileUploadAllowlist, |
| 138 | signal: ctx.signal, |
| 139 | }); |
| 140 | } |
| 141 | } |
| 142 | logger.debug(`Uploading file "${value.name}"`); |
| 143 | // File/Blob values are not subject to the upload-dir allowlist. |
| 144 | return getFileDataAfterUploadingToS3(value, { |
| 145 | toolSlug: ctx.toolSlug, |
| 146 | toolkitSlug: ctx.toolkitSlug, |
| 147 | client: ctx.client, |
| 148 | sensitiveFileUploadProtection: ctx.sensitiveFileUploadProtection, |
| 149 | fileUploadPathDenySegments: ctx.fileUploadPathDenySegments, |
| 150 | signal: ctx.signal, |
| 151 | }); |
| 152 | }; |
| 153 | |
| 154 | /** |
| 155 | * Downloads a file from S3 and returns a replacement object. |
| 156 | */ |
| 157 | const downloadS3File = async ( |
| 158 | value: Record<string, unknown>, |
| 159 | ctx: { toolSlug: string; fileDownloadDir?: string; signal?: AbortSignal } |
| 160 | ): Promise<unknown> => { |
| 161 | const { s3url, mimetype } = value as { |
| 162 | s3url: string; |
| 163 | mimetype?: string; |
| 164 | }; |
| 165 | |
| 166 | try { |
| 167 | logger.debug(`Downloading from S3: ${s3url}`); |
| 168 | |
| 169 | const dl = await downloadFileFromS3({ |
| 170 | toolSlug: ctx.toolSlug, |
| 171 | s3Url: s3url, |
| 172 | mimeType: mimetype ?? 'application/octet-stream', |
| 173 | fileDownloadDir: ctx.fileDownloadDir, |
| 174 | signal: ctx.signal, |
| 175 | }); |
| 176 | |
| 177 | logger.debug(`Downloaded → ${dl.filePath}`); |
| 178 | |
| 179 | return { |
| 180 | uri: dl.filePath, |
| 181 | file_downloaded: dl.filePath ? true : false, |
| 182 | s3url, |
| 183 | mimeType: dl.mimeType, |
| 184 | }; |
| 185 | } catch (err) { |
| 186 | logger.error(`Download failed: ${s3url}`, { cause: err }); |
| 187 | return { |
| 188 | uri: '', |
| 189 | file_downloaded: false, |
| 190 | s3url, |
| 191 | mimeType: mimetype ?? 'application/octet-stream', |
| 192 | }; |
| 193 | } |
| 194 | }; |
| 195 | |
| 196 | /** |
| 197 | * Recursively walks an arbitrary value and its matching JSON-Schema node. |
| 198 | * Whenever it encounters an object that represents a file reference |
| 199 | * (i.e. has an `s3url`), it downloads the file and returns a replacement: |
| 200 | * { |
| 201 | * uri: "<local-path>", |
| 202 | * file_downloaded: true | false, |
| 203 | * s3url: "<original S3 URL>", |
| 204 | * mimeType: "<detected-or-fallback-mime-type>" |
| 205 | * } |
| 206 | * |
| 207 | * The function is side-effect-free: it never mutates the input value. |
| 208 | */ |
| 209 | const hydrateDownloads = async ( |
| 210 | value: unknown, |
| 211 | schema: JSONSchemaProperty | undefined, |
| 212 | ctx: { toolSlug: string; fileDownloadDir?: string; signal?: AbortSignal } |
| 213 | ): Promise<unknown> => { |
| 214 | // ────────────────────────────────────────────────────────────────────────── |
| 215 | // 1. Direct S3 reference (data-driven detection) |
| 216 | // ────────────────────────────────────────────────────────────────────────── |
| 217 | if (isPlainObject(value) && typeof value.s3url === 'string') { |
| 218 | return downloadS3File(value, ctx); |
| 219 | } |
| 220 | |
| 221 | // ────────────────────────────────────────────────────────────────────────── |
| 222 | // 2. Schema-guided: Handle file_downloadable property |
| 223 | // ────────────────────────────────────────────────────────────────────────── |
| 224 | if (schema?.file_downloadable && isPlainObject(value) && typeof value.s3url === 'string') { |
| 225 | return downloadS3File(value, ctx); |
| 226 | } |
| 227 | |
| 228 | // ────────────────────────────────────────────────────────────────────────── |
| 229 | // 3. Handle anyOf/oneOf/allOf - try each variant that may contain file_downloadable |
| 230 | // ────────────────────────────────────────────────────────────────────────── |
| 231 | const schemaVariants = getSchemaVariants(schema); |
| 232 | |
| 233 | if (schemaVariants.length > 0) { |
| 234 | const downloadableVariant = findSchemaVariantWithFileProperty( |
| 235 | schema, |
| 236 | 'file_downloadable', |
| 237 | value |
| 238 | ); |
| 239 | if (downloadableVariant) { |
| 240 | return hydrateDownloads(value, downloadableVariant, ctx); |
| 241 | } |
| 242 | |
| 243 | // If no downloadable variants found, still traverse the value for s3url objects |
| 244 | return hydrateDownloads(value, undefined, ctx); |
| 245 | } |
| 246 | |
| 247 | // ────────────────────────────────────────────────────────────────────────── |
| 248 | // 4. Object → traverse each property |
| 249 | // ────────────────────────────────────────────────────────────────────────── |
| 250 | if (isPlainObject(value)) { |
| 251 | const pairs = await Promise.all( |
| 252 | Object.entries(value).map(async ([k, v]) => [ |
| 253 | k, |
| 254 | await hydrateDownloads(v, schema?.properties?.[k], ctx), |
| 255 | ]) |
| 256 | ); |
| 257 | return Object.fromEntries(pairs); |
| 258 | } |
| 259 | |
| 260 | // ────────────────────────────────────────────────────────────────────────── |
| 261 | // 5. Array → traverse each item |
| 262 | // ────────────────────────────────────────────────────────────────────────── |
| 263 | if (Array.isArray(value)) { |
| 264 | const itemSchema = schema?.items |
| 265 | ? Array.isArray(schema.items) |
| 266 | ? schema.items[0] |
| 267 | : schema.items |
| 268 | : undefined; |
| 269 | |
| 270 | return Promise.all( |
| 271 | value.map(item => hydrateDownloads(item, itemSchema as JSONSchemaProperty | undefined, ctx)) |
| 272 | ); |
| 273 | } |
| 274 | |
| 275 | // ────────────────────────────────────────────────────────────────────────── |
| 276 | // 6. Primitive → return unchanged |
| 277 | // ────────────────────────────────────────────────────────────────────────── |
| 278 | return value; |
| 279 | }; |
| 280 | |
| 281 | export class FileToolModifier { |
| 282 | private client: ComposioClient; |
| 283 | private fileUploadPathOptions: Pick< |
| 284 | GetFileDataAfterUploadingToS3Options, |
| 285 | 'sensitiveFileUploadProtection' | 'fileUploadPathDenySegments' | 'fileUploadAllowlist' |
| 286 | > & { beforeFileUpload?: beforeFileUploadModifier; fileDownloadDir?: string }; |
| 287 | |
| 288 | constructor( |
| 289 | client: ComposioClient, |
| 290 | fileUploadPathOptions: FileToolModifier['fileUploadPathOptions'] = {} |
| 291 | ) { |
| 292 | this.client = client; |
| 293 | this.fileUploadPathOptions = fileUploadPathOptions; |
| 294 | } |
| 295 | |
| 296 | async modifyToolSchema(schema: Tool): Promise<Tool> { |
| 297 | if (!schema.inputParameters?.properties) { |
| 298 | return schema; |
| 299 | } |
| 300 | |
| 301 | const inputParameters = resolveFileSchema(schema.inputParameters)!; |
| 302 | const properties = transformProperties(inputParameters.properties!); |
| 303 | |
| 304 | return { |
| 305 | ...schema, |
| 306 | inputParameters: { |
| 307 | ...inputParameters, |
| 308 | type: 'object', |
| 309 | properties, |
| 310 | }, |
| 311 | }; |
| 312 | } |
| 313 | |
| 314 | async fileUploadModifier( |
| 315 | tool: Tool, |
| 316 | options: { |
| 317 | toolSlug: string; |
| 318 | toolkitSlug?: string; |
| 319 | params: ToolExecuteParams; |
| 320 | signal?: AbortSignal; |
| 321 | } |
| 322 | ): Promise<ToolExecuteParams> { |
| 323 | const { params, toolSlug, toolkitSlug = 'unknown', signal } = options; |
| 324 | const { arguments: args } = params; |
| 325 | |
| 326 | if (!args || typeof args !== 'object') return params; |
| 327 | |
| 328 | try { |
| 329 | const newArgs = await withCancellation( |
| 330 | () => |
| 331 | walkFileUploadableLeaves(args, resolveFileSchema(tool.inputParameters), value => |
| 332 | stageFileValue(value, { |
| 333 | toolSlug, |
| 334 | toolkitSlug, |
| 335 | client: this.client, |
| 336 | ...this.fileUploadPathOptions, |
| 337 | signal, |
| 338 | }) |
| 339 | ), |
| 340 | signal |
| 341 | ); |
| 342 | return { ...params, arguments: newArgs as ToolExecuteParams['arguments'] }; |
| 343 | } catch (error) { |
| 344 | if ( |
| 345 | error instanceof ComposioRequestCancelledError || |
| 346 | error instanceof ComposioSensitiveFilePathBlockedError || |
| 347 | error instanceof ComposioFileUploadAbortedError || |
| 348 | error instanceof ComposioFileUploadPathNotAllowedError || |
| 349 | error instanceof ComposioFileNotFoundError |
| 350 | ) { |
| 351 | throw error; |
| 352 | } |
| 353 | throw new ComposioFileUploadError('Failed to upload file', { |
| 354 | cause: error, |
| 355 | }); |
| 356 | } |
| 357 | } |
| 358 | |
| 359 | async fileDownloadModifier( |
| 360 | tool: Tool, |
| 361 | options: { |
| 362 | toolSlug: string; |
| 363 | toolkitSlug: string; |
| 364 | result: ToolExecuteResponse; |
| 365 | signal?: AbortSignal; |
| 366 | } |
| 367 | ): Promise<ToolExecuteResponse> { |
| 368 | const { result, toolSlug, signal } = options; |
| 369 | |
| 370 | const dataWithDownloads = await hydrateDownloads( |
| 371 | result.data, |
| 372 | resolveFileSchema(tool.outputParameters), |
| 373 | { |
| 374 | toolSlug, |
| 375 | fileDownloadDir: this.fileUploadPathOptions.fileDownloadDir, |
| 376 | signal, |
| 377 | } |
| 378 | ); |
| 379 | |
| 380 | return { ...result, data: dataWithDownloads as typeof result.data }; |
| 381 | } |
| 382 | } |