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 382 lines 14 KB
Raw
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 }