@devries-cameron20 / composio-1 / commits / 93b67e8b2
Fork 0

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

fix(ts-sdk): handle file upload list unions (#3374)

## Summary This updates the TypeScript SDK's automatic file upload/download modifier to handle tool schemas that accept either a single file or a list of files. Tools can expose file inputs as a composed schema such as: ```json { "anyOf": [ { "type": "object", "file_uploadable": true }, { "type": "array", "items": { "type": "object", "file_uploadable": true } } ] } ``` When auto-upload is enabled, the SDK presents those file-uploadable objects to models as file path strings. If the model supplies a list of local paths, the old upload resolver selected the first file-bearing branch, usually the single-file branch, and left the list unchanged. That means the backend could receive local paths instead of staged `{ name, mimetype, s3key }` descriptors. ## Changes - Adds runtime-shape-aware composed-schema selection for file upload/download modifiers. - Chooses the array branch for list values while preserving single-file behavior for string/File values. - Preserves the existing fallback behavior: if no runtime shape matches, use the first file-bearing variant. - Keeps `anyOf`, `oneOf`, and `allOf` on the same composed-schema path used by the SDK today. - Adds regression coverage for single-file vs multi-file unions, array item unions, and download parity. - Adds a patch changeset for `@composio/core`. ## Why Some file-capable tool schemas are backward compatible at the API level by accepting both a single file and multiple files. The TypeScript SDK should transform a list of local paths into a list of staged file descriptors, just as it already does for direct array schemas. ## Verification - `pnpm --filter @composio/core exec prettier --check src/utils/modifiers/FileToolModifier.node.ts test/tools/fileModifiers.test.ts` Blocked locally: - `pnpm --filter @composio/core test -- fileModifiers.test.ts` fails before collecting tests because this workspace cannot resolve the unbuilt `@composio/json-schema-to-zod` package entry. - `pnpm --filter @composio/core typecheck:tsc` is also blocked by existing local generated-client/workspace dependency errors unrelated to this patch. --------- Co-authored-by: Zen <zen@composio.dev>

Shrey Singla committed May 14, 2026 at 13:38 UTC 93b67e8b2f1a01895df773d8902c052960cf47ad
3 files changed +344 -35
.changeset/file-uploadable-list-unions.md new
+7
@@ -0,0 +1,7 @@
1 +---
2 +'@composio/core': patch
3 +---
4 +
5 +Fix automatic file upload/download substitution for file schemas that accept either a single file or a list of files.
6 +
7 +The file modifier now selects composed-schema branches by runtime value shape, so `anyOf(file, array<file>)` uploads or downloads each file when the tool receives a list while preserving existing single-file behavior.
ts/packages/core/src/utils/modifiers/FileToolModifier.node.ts
+70 -35
@@ -22,10 +22,62 @@ import {
22 import {
23 isPlainObject,
24 transformProperties,
25 - schemaHasFileUploadable,
26 - schemaHasFileDownloadable,
25 + schemaHasFileProperty,
26 } from './FileToolModifier.utils.neutral';
27
28 +const getSchemaVariants = (schema: JSONSchemaProperty | undefined): JSONSchemaProperty[] => [
29 + ...(schema?.anyOf ?? []),
30 + ...(schema?.oneOf ?? []),
31 + ...(schema?.allOf ?? []),
32 +];
33 +
34 +const jsonSchemaTypeMatchesValue = (schema: JSONSchemaProperty, value: unknown): boolean => {
35 + const schemaType = schema.type;
36 +
37 + if (Array.isArray(schemaType)) {
38 + return schemaType.some(type => jsonSchemaTypeMatchesValue({ ...schema, type }, value));
39 + }
40 +
41 + if (schemaType === undefined) {
42 + if (schema.properties) return isPlainObject(value);
43 + if (schema.items) return Array.isArray(value);
44 + return false;
45 + }
46 +
47 + switch (schemaType) {
48 + case 'array':
49 + return Array.isArray(value);
50 + case 'object':
51 + return isPlainObject(value);
52 + case 'string':
53 + return typeof value === 'string';
54 + case 'integer':
55 + return Number.isInteger(value);
56 + case 'number':
57 + return typeof value === 'number';
58 + case 'boolean':
59 + return typeof value === 'boolean';
60 + case 'null':
61 + return value === null;
62 + default:
63 + return false;
64 + }
65 +};
66 +
67 +const findSchemaVariantWithFileProperty = (
68 + schema: JSONSchemaProperty | undefined,
69 + property: 'file_uploadable' | 'file_downloadable',
70 + value: unknown
71 +): JSONSchemaProperty | undefined => {
72 + const candidates = getSchemaVariants(schema).filter(variant =>
73 + schemaHasFileProperty(variant, property)
74 + );
75 +
76 + return (
77 + candidates.find(candidate => jsonSchemaTypeMatchesValue(candidate, value)) ?? candidates[0]
78 + );
79 +};
80 +
81 /**
82 * Recursively walks a runtime value and its matching JSON-Schema node,
83 * uploading any string path whose schema node has `file_uploadable: true`.
@@ -128,27 +180,18 @@ const hydrateFiles = async (
180 }
181
182 // ──────────────────────────────────────────────────────────────────────────
131 - // 2. Handle anyOf/oneOf/allOf — pick the first variant that contains a
132 - // file_uploadable property and hydrate against it.
183 + // 2. Handle anyOf/oneOf/allOf — pick the file-bearing variant whose
184 + // JSON Schema shape matches the runtime value, then hydrate against it.
185 //
186 // We deliberately do NOT loop over every uploadable variant. With `oneOf`,
187 // exactly one variant should apply at runtime, and applying multiple would
188 // upload the same file once per variant — two presigned-URL round-trips and
137 - // two S3 PUTs for a two-variant `oneOf`. Matching the Python SDK
138 - // (`_find_uploadable_schema_variant`), we short-circuit on the first match.
189 + // two S3 PUTs for a two-variant `oneOf`. If no runtime shape matches, fall
190 + // back to the first file-bearing variant to preserve historical behavior.
191 // ──────────────────────────────────────────────────────────────────────────
140 - const schemaVariants = [
141 - ...(schema?.anyOf ?? []),
142 - ...(schema?.oneOf ?? []),
143 - ...(schema?.allOf ?? []),
144 - ];
145 -
146 - if (schemaVariants.length > 0) {
147 - const firstUploadableVariant = schemaVariants.find(schemaHasFileUploadable);
148 - if (firstUploadableVariant) {
149 - return hydrateFiles(value, firstUploadableVariant, ctx);
150 - }
151 - // If no uploadable variants found, fall through to check base properties
192 + const uploadableVariant = findSchemaVariantWithFileProperty(schema, 'file_uploadable', value);
193 + if (uploadableVariant) {
194 + return hydrateFiles(value, uploadableVariant, ctx);
195 }
196
197 // ──────────────────────────────────────────────────────────────────────────
@@ -257,28 +300,20 @@ const hydrateDownloads = async (
300 // ──────────────────────────────────────────────────────────────────────────
301 // 3. Handle anyOf/oneOf/allOf - try each variant that may contain file_downloadable
302 // ──────────────────────────────────────────────────────────────────────────
260 - const schemaVariants = [
261 - ...(schema?.anyOf ?? []),
262 - ...(schema?.oneOf ?? []),
263 - ...(schema?.allOf ?? []),
264 - ];
303 + const schemaVariants = getSchemaVariants(schema);
304
305 if (schemaVariants.length > 0) {
267 - // Find variants that have file_downloadable properties
268 - const downloadableVariants = schemaVariants.filter(schemaHasFileDownloadable);
269 -
270 - // Process with each downloadable variant
271 - let result = value;
272 - for (const variant of downloadableVariants) {
273 - result = await hydrateDownloads(result, variant, ctx);
306 + const downloadableVariant = findSchemaVariantWithFileProperty(
307 + schema,
308 + 'file_downloadable',
309 + value
310 + );
311 + if (downloadableVariant) {
312 + return hydrateDownloads(value, downloadableVariant, ctx);
313 }
314
315 // If no downloadable variants found, still traverse the value for s3url objects
277 - if (downloadableVariants.length === 0) {
278 - return hydrateDownloads(value, undefined, ctx);
279 - }
280 -
281 - return result;
316 + return hydrateDownloads(value, undefined, ctx);
317 }
318
319 // ──────────────────────────────────────────────────────────────────────────
ts/packages/core/test/tools/fileModifiers.test.ts
+267
@@ -790,6 +790,178 @@ describe('FileToolModifier', () => {
790 expect(result.arguments?.fileInput).toEqual(mockFileData);
791 });
792
793 + it('should upload each file when anyOf accepts a single file or an array of files', async () => {
794 + const mockFileData1 = {
795 + name: 'file1.txt',
796 + mimetype: 'text/plain',
797 + s3key: 'uploads/file1.txt',
798 + };
799 + const mockFileData2 = {
800 + name: 'file2.txt',
801 + mimetype: 'text/plain',
802 + s3key: 'uploads/file2.txt',
803 + };
804 + vi.mocked(fileUtils.getFileDataAfterUploadingToS3)
805 + .mockResolvedValueOnce(mockFileData1)
806 + .mockResolvedValueOnce(mockFileData2);
807 +
808 + const toolWithSingleOrArrayFile: Tool = {
809 + slug: 'test-tool',
810 + name: 'Test Tool',
811 + description: 'A test tool',
812 + tags: ['test'],
813 + inputParameters: {
814 + type: 'object',
815 + properties: {
816 + attachment: {
817 + anyOf: [
818 + { type: 'string', file_uploadable: true },
819 + {
820 + type: 'array',
821 + items: { type: 'string', file_uploadable: true },
822 + },
823 + ],
824 + },
825 + },
826 + },
827 + version: '20251201_01',
828 + availableVersions: ['20251201_01'],
829 + };
830 +
831 + const result = await fileToolModifier.fileUploadModifier(toolWithSingleOrArrayFile, {
832 + toolSlug: 'test-tool',
833 + toolkitSlug: 'test-toolkit',
834 + params: {
835 + arguments: {
836 + attachment: ['/path/to/file1.txt', '/path/to/file2.txt'],
837 + },
838 + userId: 'test-user',
839 + },
840 + });
841 +
842 + expect(fileUtils.getFileDataAfterUploadingToS3).toHaveBeenCalledTimes(2);
843 + expect(fileUtils.getFileDataAfterUploadingToS3).toHaveBeenNthCalledWith(
844 + 1,
845 + '/path/to/file1.txt',
846 + {
847 + toolSlug: 'test-tool',
848 + toolkitSlug: 'test-toolkit',
849 + client: mockClient,
850 + }
851 + );
852 + expect(fileUtils.getFileDataAfterUploadingToS3).toHaveBeenNthCalledWith(
853 + 2,
854 + '/path/to/file2.txt',
855 + {
856 + toolSlug: 'test-tool',
857 + toolkitSlug: 'test-toolkit',
858 + client: mockClient,
859 + }
860 + );
861 + expect(result.arguments?.attachment).toEqual([mockFileData1, mockFileData2]);
862 + });
863 +
864 + it('should keep single-file behavior when anyOf also accepts an array of files', async () => {
865 + const mockFileData = {
866 + name: 'file.txt',
867 + mimetype: 'text/plain',
868 + s3key: 'uploads/file.txt',
869 + };
870 + vi.mocked(fileUtils.getFileDataAfterUploadingToS3).mockResolvedValue(mockFileData);
871 +
872 + const toolWithSingleOrArrayFile: Tool = {
873 + slug: 'test-tool',
874 + name: 'Test Tool',
875 + description: 'A test tool',
876 + tags: ['test'],
877 + inputParameters: {
878 + type: 'object',
879 + properties: {
880 + attachment: {
881 + anyOf: [
882 + { type: 'string', file_uploadable: true },
883 + {
884 + type: 'array',
885 + items: { type: 'string', file_uploadable: true },
886 + },
887 + ],
888 + },
889 + },
890 + },
891 + version: '20251201_01',
892 + availableVersions: ['20251201_01'],
893 + };
894 +
895 + const result = await fileToolModifier.fileUploadModifier(toolWithSingleOrArrayFile, {
896 + toolSlug: 'test-tool',
897 + toolkitSlug: 'test-toolkit',
898 + params: {
899 + arguments: {
900 + attachment: '/path/to/file.txt',
901 + },
902 + userId: 'test-user',
903 + },
904 + });
905 +
906 + expect(fileUtils.getFileDataAfterUploadingToS3).toHaveBeenCalledTimes(1);
907 + expect(fileUtils.getFileDataAfterUploadingToS3).toHaveBeenCalledWith('/path/to/file.txt', {
908 + toolSlug: 'test-tool',
909 + toolkitSlug: 'test-toolkit',
910 + client: mockClient,
911 + });
912 + expect(result.arguments?.attachment).toEqual(mockFileData);
913 + });
914 +
915 + it('should upload file array items whose item schema is an anyOf file branch', async () => {
916 + const mockFileData1 = {
917 + name: 'file1.txt',
918 + mimetype: 'text/plain',
919 + s3key: 'uploads/file1.txt',
920 + };
921 + const mockFileData2 = {
922 + name: 'file2.txt',
923 + mimetype: 'text/plain',
924 + s3key: 'uploads/file2.txt',
925 + };
926 + vi.mocked(fileUtils.getFileDataAfterUploadingToS3)
927 + .mockResolvedValueOnce(mockFileData1)
928 + .mockResolvedValueOnce(mockFileData2);
929 +
930 + const toolWithArrayItemAnyOf: Tool = {
931 + slug: 'test-tool',
932 + name: 'Test Tool',
933 + description: 'A test tool',
934 + tags: ['test'],
935 + inputParameters: {
936 + type: 'object',
937 + properties: {
938 + attachments: {
939 + type: 'array',
940 + items: {
941 + anyOf: [{ type: 'string', file_uploadable: true }, { type: 'null' }],
942 + },
943 + },
944 + },
945 + },
946 + version: '20251201_01',
947 + availableVersions: ['20251201_01'],
948 + };
949 +
950 + const result = await fileToolModifier.fileUploadModifier(toolWithArrayItemAnyOf, {
951 + toolSlug: 'test-tool',
952 + toolkitSlug: 'test-toolkit',
953 + params: {
954 + arguments: {
955 + attachments: ['/path/to/file1.txt', null, '/path/to/file2.txt'],
956 + },
957 + userId: 'test-user',
958 + },
959 + });
960 +
961 + expect(fileUtils.getFileDataAfterUploadingToS3).toHaveBeenCalledTimes(2);
962 + expect(result.arguments?.attachments).toEqual([mockFileData1, null, mockFileData2]);
963 + });
964 +
965 it('should not upload when value is null for anyOf with null variant', async () => {
966 const toolWithAnyOf: Tool = {
967 slug: 'test-tool',
@@ -1398,6 +1570,101 @@ describe('FileToolModifier', () => {
1570 });
1571 });
1572
1573 + it('should download each file when anyOf accepts a single file or an array of files', async () => {
1574 + const mockDownloadResult1 = {
1575 + name: 'file1.txt',
1576 + mimeType: 'text/plain',
1577 + s3Url: 'downloads/file1.txt',
1578 + filePath: '/downloaded/file1.txt',
1579 + };
1580 + const mockDownloadResult2 = {
1581 + name: 'file2.txt',
1582 + mimeType: 'text/plain',
1583 + s3Url: 'downloads/file2.txt',
1584 + filePath: '/downloaded/file2.txt',
1585 + };
1586 + vi.mocked(fileUtils.downloadFileFromS3)
1587 + .mockResolvedValueOnce(mockDownloadResult1)
1588 + .mockResolvedValueOnce(mockDownloadResult2);
1589 +
1590 + const toolWithSingleOrArrayFile: Tool = {
1591 + slug: 'test-tool',
1592 + name: 'Test Tool',
1593 + description: 'A test tool',
1594 + tags: ['test'],
1595 + outputParameters: {
1596 + type: 'object',
1597 + properties: {
1598 + attachment: {
1599 + anyOf: [
1600 + {
1601 + type: 'object',
1602 + file_downloadable: true,
1603 + properties: {
1604 + s3url: { type: 'string' },
1605 + mimetype: { type: 'string' },
1606 + },
1607 + },
1608 + {
1609 + type: 'array',
1610 + items: {
1611 + type: 'object',
1612 + file_downloadable: true,
1613 + properties: {
1614 + s3url: { type: 'string' },
1615 + mimetype: { type: 'string' },
1616 + },
1617 + },
1618 + },
1619 + ],
1620 + },
1621 + },
1622 + },
1623 + version: '20251201_01',
1624 + availableVersions: ['20251201_01'],
1625 + };
1626 +
1627 + const modifiedResult = await fileToolModifier.fileDownloadModifier(
1628 + toolWithSingleOrArrayFile,
1629 + {
1630 + toolSlug: 'test-tool',
1631 + toolkitSlug: 'test-toolkit',
1632 + result: {
1633 + data: {
1634 + attachment: [
1635 + {
1636 + s3url: 'https://s3.example.com/file1.txt',
1637 + mimetype: 'text/plain',
1638 + },
1639 + {
1640 + s3url: 'https://s3.example.com/file2.txt',
1641 + mimetype: 'text/plain',
1642 + },
1643 + ],
1644 + },
1645 + error: null,
1646 + successful: true,
1647 + },
1648 + }
1649 + );
1650 +
1651 + expect(fileUtils.downloadFileFromS3).toHaveBeenCalledTimes(2);
1652 + expect(modifiedResult.data.attachment).toEqual([
1653 + {
1654 + uri: '/downloaded/file1.txt',
1655 + file_downloaded: true,
1656 + s3url: 'https://s3.example.com/file1.txt',
1657 + mimeType: 'text/plain',
1658 + },
1659 + {
1660 + uri: '/downloaded/file2.txt',
1661 + file_downloaded: true,
1662 + s3url: 'https://s3.example.com/file2.txt',
1663 + mimeType: 'text/plain',
1664 + },
1665 + ]);
1666 + });
1667 +
1668 it('should not download when value is null for anyOf with null variant', async () => {
1669 const toolWithAnyOf: Tool = {
1670 slug: 'test-tool',