@devries-cameron20 / composio-1 / commits / fe66cbeb7
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(sdk): omit empty file-uploadable arguments from tool execution

Both SDKs forwarded "" for a file_uploadable parameter (e.g. Gmail attachment) verbatim to the backend, which rejected it with a Pydantic validation error. Python only dropped it inside the opt-in auto-upload walker; TypeScript never did, and with auto-upload on it tried to upload the empty string. Run a schema-aware, upload-free pass on the default execute path that omits empty file values, and reuse the same walker for staging when auto-upload is enabled. Closes #4233

jkomyno committed Aug 25, 2026 at 01:58 UTC fe66cbeb77ce00952eeed582b7c659fdde9f6c54
9 files changed +569 -221
.changeset/drop-empty-file-uploads.md new
+5
@@ -0,0 +1,5 @@
1 +---
2 +'@composio/core': patch
3 +---
4 +
5 +Omit empty-string file-uploadable arguments from tool execution requests instead of forwarding them to the backend, which rejected them with "Input should be a valid dictionary or instance of FileUploadable". This now also applies when `dangerouslyAllowAutoUploadDownloadFiles` is off, and with it on an empty value is no longer attempted as an upload.
python/composio/core/models/_files.py
+57 -18
@@ -1,5 +1,6 @@
1 from __future__ import annotations
2
3 +import functools
4 import hashlib
5 import os
6 import typing as t
@@ -1039,13 +1040,23 @@ class FileHelper(WithLogger):
1040 value=value,
1041 )
1042
1043 + @staticmethod
1044 + def _drop_empty_file_value(value: t.Any) -> t.Any:
1045 + """Leaf handler: ``None``/``""`` at a file leaf mean "no file".
1046 +
1047 + Neither is a staged ``{name, mimetype, s3key}`` descriptor, so the
1048 + backend rejects them with a validation error while callers (and the
1049 + playground UI) mean "absent". The walker omits the key instead.
1050 + """
1051 + return _DELETE_VALUE if value is None or value == "" else value
1052 +
1053 def _upload_file_value(
1054 self,
1055 value: t.Any,
1056 tool: Tool,
1057 before_file_upload: t.Optional[BeforeFileUpload],
1058 ) -> t.Any:
1048 - if value is None or value == "":
1059 + if self._drop_empty_file_value(value) is _DELETE_VALUE:
1060 return _DELETE_VALUE
1061
1062 return FileUploadable.from_path(
@@ -1063,20 +1074,18 @@ class FileHelper(WithLogger):
1074 self,
1075 value: t.Any,
1076 schema: t.Optional[t.Dict],
1066 - tool: Tool,
1067 - *,
1068 - before_file_upload: t.Optional[BeforeFileUpload] = None,
1077 + leaf: t.Callable[[t.Any], t.Any],
1078 ) -> t.Any:
1070 - """Return ``value`` with file-uploadable leaves staged for execution."""
1079 + """Return ``value`` with every ``file_uploadable`` leaf passed through ``leaf``.
1080 +
1081 + A leaf may return ``_DELETE_VALUE`` to omit the key/item from its
1082 + parent container.
1083 + """
1084 if not isinstance(schema, dict):
1085 return value
1086
1087 if schema.get("file_uploadable", False):
1075 - return self._upload_file_value(
1076 - value=value,
1077 - tool=tool,
1078 - before_file_upload=before_file_upload,
1079 - )
1088 + return leaf(value)
1089
1090 uploadable_variant = self._find_uploadable_schema_variant(
1091 schema=schema,
@@ -1086,8 +1095,7 @@ class FileHelper(WithLogger):
1095 return self._substitute_file_upload_value(
1096 value=value,
1097 schema=uploadable_variant,
1089 - tool=tool,
1090 - before_file_upload=before_file_upload,
1098 + leaf=leaf,
1099 )
1100
1101 if isinstance(value, dict) and "properties" in schema:
@@ -1098,8 +1106,7 @@ class FileHelper(WithLogger):
1106 processed_item = self._substitute_file_upload_value(
1107 value=item,
1108 schema=item_schema,
1101 - tool=tool,
1102 - before_file_upload=before_file_upload,
1109 + leaf=leaf,
1110 )
1111 if processed_item is not _DELETE_VALUE:
1112 processed[key] = processed_item
@@ -1115,8 +1122,7 @@ class FileHelper(WithLogger):
1122 processed_item = self._substitute_file_upload_value(
1123 value=item,
1124 schema=items_schema,
1118 - tool=tool,
1119 - before_file_upload=before_file_upload,
1125 + leaf=leaf,
1126 )
1127 if processed_item is not _DELETE_VALUE:
1128 processed_items.append(processed_item)
@@ -1131,12 +1137,19 @@ class FileHelper(WithLogger):
1137 request: t.Dict,
1138 *,
1139 before_file_upload: t.Optional[BeforeFileUpload] = None,
1140 + leaf: t.Optional[t.Callable[[t.Any], t.Any]] = None,
1141 ) -> t.Dict:
1142 + if leaf is None:
1143 + leaf = functools.partial(
1144 + self._upload_file_value,
1145 + tool=tool,
1146 + before_file_upload=before_file_upload,
1147 + )
1148 +
1149 processed = self._substitute_file_upload_value(
1150 value=request,
1151 schema=schema,
1138 - tool=tool,
1139 - before_file_upload=before_file_upload,
1152 + leaf=leaf,
1153 )
1154 if processed is request:
1155 return request
@@ -1177,6 +1190,32 @@ class FileHelper(WithLogger):
1190 before_file_upload=before_file_upload,
1191 )
1192
1193 + def drop_empty_file_uploads(self, tool: Tool, request: t.Dict) -> t.Dict:
1194 + """Omit ``None``/``""`` at ``file_uploadable`` leaves without uploading.
1195 +
1196 + This is the half of :meth:`substitute_file_uploads` that needs no
1197 + filesystem access, so it runs even when automatic upload is disabled:
1198 + an empty file value is never a valid staged descriptor and the backend
1199 + would reject it (issue #4233). Any other value -- a local path, a
1200 + staged descriptor, a list -- is forwarded untouched. Same mutation
1201 + contract as :meth:`substitute_file_uploads`.
1202 + """
1203 + schema = dereference_json_schema(
1204 + tool.input_parameters, on_unresolved="sentinel"
1205 + )
1206 + # Every execution takes this path by default, so leave requests for
1207 + # tools without a file input completely alone (identity included)
1208 + # instead of rebuilding their nested dicts.
1209 + if not self._file_uploadable(schema):
1210 + return request
1211 +
1212 + return self._substitute_file_uploads_recursively(
1213 + tool=tool,
1214 + schema=schema,
1215 + request=request,
1216 + leaf=self._drop_empty_file_value,
1217 + )
1218 +
1219 def _is_file_downloadable(self, schema: t.Dict) -> bool:
1220 """Check if a schema has file_downloadable property."""
1221 return self._has_file_property(schema, "file_downloadable")
python/composio/core/models/tools.py
+10
@@ -515,6 +515,10 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
515 request=arguments,
516 before_file_upload=bfu,
517 )
518 + else:
519 + arguments = self._file_helper.drop_empty_file_uploads(
520 + tool=tool, request=arguments
521 + )
522
523 toolkit_slug = _toolkit_slug(tool, "composio")
524
@@ -676,6 +680,12 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
680 request=arguments,
681 before_file_upload=bfu,
682 )
683 + else:
684 + # Auto-upload is opt-in, but "no file" must still be sent as an
685 + # omitted key rather than ``""``/``None`` (issue #4233).
686 + arguments = self._file_helper.drop_empty_file_uploads(
687 + tool=tool, request=arguments
688 + )
689
690 if modifiers is not None:
691 type_before_exec: t.Literal["before_execute"] = "before_execute"
python/tests/test_auto_upload_download_files.py
+66
@@ -456,6 +456,72 @@ class TestAutoUploadDownloadFilesDisabled:
456
457 mock_substitute.assert_not_called()
458
459 + def test_execute_drops_empty_file_values_when_disabled(
460 + self, mock_client, mock_provider
461 + ):
462 + """Issue #4233: with auto-upload off, ``attachment: ""`` must be
463 + omitted from the request instead of forwarded to the backend, while a
464 + real value is forwarded as-is (not uploaded)."""
465 + tools = Tools(
466 + client=mock_client,
467 + provider=mock_provider,
468 + toolkit_versions={"gmail": "20251201_01"},
469 + )
470 +
471 + file_uploadable = {
472 + "type": "object",
473 + "file_uploadable": True,
474 + "properties": {
475 + "name": {"type": "string"},
476 + "mimetype": {"type": "string"},
477 + "s3key": {"type": "string"},
478 + },
479 + }
480 + mock_tool = create_mock_tool(
481 + slug="GMAIL_CREATE_DRAFT",
482 + toolkit_slug="gmail",
483 + input_parameters={
484 + "type": "object",
485 + "properties": {
486 + "subject": {"type": "string"},
487 + "attachment": {
488 + "anyOf": [
489 + file_uploadable,
490 + {"type": "array", "items": file_uploadable},
491 + {"type": "null"},
492 + ]
493 + },
494 + },
495 + },
496 + )
497 + mock_execute_response = Mock()
498 + mock_execute_response.model_dump.return_value = {
499 + "data": {},
500 + "error": None,
501 + "successful": True,
502 + }
503 + mock_client.tools.execute.return_value = mock_execute_response
504 +
505 + with patch.object(
506 + tools, "get_raw_composio_tool_by_slug", return_value=mock_tool
507 + ):
508 + for value, expected in (
509 + ("", {"subject": "Test"}),
510 + (None, {"subject": "Test"}),
511 + (
512 + "/path/to/file.txt",
513 + {"subject": "Test", "attachment": "/path/to/file.txt"},
514 + ),
515 + ):
516 + mock_client.tools.execute.reset_mock()
517 + tools.execute(
518 + slug="GMAIL_CREATE_DRAFT",
519 + arguments={"subject": "Test", "attachment": value},
520 + dangerously_skip_version_check=True,
521 + )
522 + sent = mock_client.tools.execute.call_args.kwargs["arguments"]
523 + assert sent == expected, value
524 +
525 def test_execute_skips_file_downloads_when_disabled(
526 self, mock_client, mock_provider
527 ):
python/tests/test_files.py
+66
@@ -779,6 +779,72 @@ class TestFileUploadSubstitutionWithUnionTypes:
779 # None/empty values should be removed
780 assert "fileInput" not in result
781
782 + def test_drop_empty_file_uploads_omits_empty_leaves_without_uploading(
783 + self, file_helper, mock_tool
784 + ):
785 + """Issue #4233: ``""``/``None`` at a file leaf mean "no file" even when
786 + auto-upload is off, while any other value is forwarded untouched."""
787 + file_uploadable = {
788 + "type": "object",
789 + "file_uploadable": True,
790 + "title": "FileUploadable",
791 + "properties": {
792 + "name": {"type": "string"},
793 + "mimetype": {"type": "string"},
794 + "s3key": {"type": "string"},
795 + },
796 + "required": ["name", "mimetype", "s3key"],
797 + }
798 + mock_tool.input_parameters = {
799 + "type": "object",
800 + "properties": {
801 + "subject": {"type": "string"},
802 + "attachment": {
803 + "anyOf": [
804 + file_uploadable,
805 + {"type": "array", "items": file_uploadable},
806 + {"type": "null"},
807 + ],
808 + "default": None,
809 + },
810 + "extra": {
811 + "anyOf": [
812 + {"type": "array", "items": file_uploadable},
813 + {"type": "null"},
814 + ]
815 + },
816 + "nested": {
817 + "type": "object",
818 + "properties": {"file": {"$ref": "#/$defs/F"}},
819 + },
820 + "thread_id": {"type": "string"},
821 + },
822 + "$defs": {"F": file_uploadable},
823 + }
824 + staged = {"name": "a.txt", "mimetype": "text/plain", "s3key": "k"}
825 + request = {
826 + "subject": "Test",
827 + "attachment": "",
828 + "extra": [None, "", staged, "/tmp/keep.txt"],
829 + "nested": {"file": None},
830 + "thread_id": "",
831 + }
832 +
833 + with patch.object(FileUploadable, "from_path") as from_path:
834 + result = file_helper.drop_empty_file_uploads(
835 + tool=mock_tool, request=request
836 + )
837 +
838 + from_path.assert_not_called()
839 + assert result is request
840 + assert result == {
841 + "subject": "Test",
842 + "extra": [staged, "/tmp/keep.txt"],
843 + "nested": {},
844 + # non-file empty strings are not the walker's business
845 + "thread_id": "",
846 + }
847 +
848 def test_substitute_upload_empty_string_in_anyof(self, file_helper, mock_tool):
849 """Test that empty string values in anyOf with file_uploadable are handled."""
850 mock_tool.input_parameters = {
ts/packages/core/src/models/Tools.ts
+38 -22
@@ -54,7 +54,11 @@ import { handleToolExecutionError } from '../errors/ToolErrors';
54 import type { SessionExecuteParams } from '@composio/client/resources/tool-router/session/session.mjs';
55 import { CONFIG_DEFAULTS } from '../utils/config-defaults';
56 import { resolveEffectiveUploadAllowlist } from '../utils/fileDirs';
57 -import { schemaHasFileUploadable } from '../utils/modifiers/FileToolModifier.utils.neutral';
57 +import {
58 + dropEmptyFileUploads,
59 + schemaHasFileUploadable,
60 +} from '../utils/modifiers/FileToolModifier.utils.neutral';
61 +import { dereferenceJsonSchema } from '../utils/jsonSchema';
62 import { ComposioRequestOptions } from '../types/requestOptions.types';
63 import { withCancellation } from '../utils/cancellation';
64 import { ComposioRequestCancelledError } from '../errors/SDKErrors';
@@ -284,26 +288,38 @@ export class Tools<
288 if (requestOptions?.signal?.aborted) {
289 throw new ComposioRequestCancelledError();
290 }
287 - } else if (
288 - schemaHasFileUploadable(tool.inputParameters) &&
289 - !this.warnedAutoUploadDisabledForTool.has(toolSlug)
290 - ) {
291 - // With auto-upload off, the raw `{ name, mimetype, s3key }` shape is
292 - // what the LLM / caller sees on `tool.inputParameters`. LLMs can't
293 - // produce a valid `s3key` and will hallucinate one, which then fails
294 - // at the staging-lookup step on the backend. Nudge the caller toward
295 - // manual staging or opting into auto-upload.
296 - this.warnedAutoUploadDisabledForTool.add(toolSlug);
297 - logger.warn(
298 - `Tool "${toolSlug}" (toolkit "${toolkitSlug}") has a file-uploadable input, but ` +
299 - `\`dangerouslyAllowAutoUploadDownloadFiles\` is disabled. The SDK will forward ` +
300 - `the file argument as-is; if it isn't already a staged ` +
301 - `{ name, mimetype, s3key } descriptor, the backend will reject the call. Either:\n` +
302 - ` 1) Stage the file yourself: \`const f = await composio.files.upload({ file, toolSlug, toolkitSlug }); ` +
303 - `await composio.tools.execute('${toolSlug}', { userId, arguments: { <fileField>: f } })\`, or\n` +
304 - ` 2) Enable auto-upload with a scoped allowlist: ` +
305 - `\`new Composio({ dangerouslyAllowAutoUploadDownloadFiles: true, fileUploadDirs: ['/safe/dir'] })\`.`
306 - );
291 + } else if (tool.inputParameters && schemaHasFileUploadable(tool.inputParameters)) {
292 + // Auto-upload is opt-in, but "no file" must still be sent as an
293 + // omitted key rather than `''`, which the backend rejects
294 + // (https://github.com/ComposioHQ/composio/issues/4233).
295 + if (modifiedParams.arguments) {
296 + modifiedParams = {
297 + ...modifiedParams,
298 + arguments: (await dropEmptyFileUploads(
299 + modifiedParams.arguments,
300 + dereferenceJsonSchema(tool.inputParameters, { onUnresolved: 'sentinel' })
301 + )) as ToolExecuteParams['arguments'],
302 + };
303 + }
304 +
305 + if (!this.warnedAutoUploadDisabledForTool.has(toolSlug)) {
306 + // With auto-upload off, the raw `{ name, mimetype, s3key }` shape is
307 + // what the LLM / caller sees on `tool.inputParameters`. LLMs can't
308 + // produce a valid `s3key` and will hallucinate one, which then fails
309 + // at the staging-lookup step on the backend. Nudge the caller toward
310 + // manual staging or opting into auto-upload.
311 + this.warnedAutoUploadDisabledForTool.add(toolSlug);
312 + logger.warn(
313 + `Tool "${toolSlug}" (toolkit "${toolkitSlug}") has a file-uploadable input, but ` +
314 + `\`dangerouslyAllowAutoUploadDownloadFiles\` is disabled. The SDK will forward ` +
315 + `the file argument as-is; if it isn't already a staged ` +
316 + `{ name, mimetype, s3key } descriptor, the backend will reject the call. Either:\n` +
317 + ` 1) Stage the file yourself: \`const f = await composio.files.upload({ file, toolSlug, toolkitSlug }); ` +
318 + `await composio.tools.execute('${toolSlug}', { userId, arguments: { <fileField>: f } })\`, or\n` +
319 + ` 2) Enable auto-upload with a scoped allowlist: ` +
320 + `\`new Composio({ dangerouslyAllowAutoUploadDownloadFiles: true, fileUploadDirs: ['/safe/dir'] })\`.`
321 + );
322 + }
323 }
324 // apply the before execute modifiers
325 if (modifiers?.beforeExecute) {
@@ -1308,7 +1324,7 @@ export class Tools<
1324 * @deprecated The `customConnectionData` proxy param is deprecated and will be
1325 * removed in a future release. Use `customAuthParams` instead.
1326 */
1311 - // @ts-ignore
1327 + // @ts-expect-error
1328 custom_connection_data: toolProxyParams.data.customConnectionData,
1329 } as ComposioToolProxyParams;
1330 return withCancellation(
ts/packages/core/src/utils/modifiers/FileToolModifier.node.ts
+85 -181
@@ -22,9 +22,13 @@ import {
22 type GetFileDataAfterUploadingToS3Options,
23 } from '../fileUtils.node';
24 import {
25 + DELETE_VALUE,
26 + findSchemaVariantWithFileProperty,
27 + getSchemaVariants,
28 + isEmptyFileValue,
29 isPlainObject,
30 transformProperties,
27 - schemaHasFileProperty,
31 + walkFileUploadableLeaves,
32 } from './FileToolModifier.utils.neutral';
33 import { dereferenceJsonSchema } from '../jsonSchema';
34 import { withCancellation } from '../cancellation';
@@ -44,68 +48,14 @@ const resolveFileSchema = <Schema extends JSONSchemaProperty>(
48 ): Schema | undefined =>
49 schema ? dereferenceJsonSchema(schema, { onUnresolved: 'sentinel' }) : schema;
50
47 -const getSchemaVariants = (schema: JSONSchemaProperty | undefined): JSONSchemaProperty[] => [
48 - ...(schema?.anyOf ?? []),
49 - ...(schema?.oneOf ?? []),
50 - ...(schema?.allOf ?? []),
51 -];
52 -
53 -const jsonSchemaTypeMatchesValue = (schema: JSONSchemaProperty, value: unknown): boolean => {
54 - const schemaType = schema.type;
55 -
56 - if (Array.isArray(schemaType)) {
57 - return schemaType.some(type => jsonSchemaTypeMatchesValue({ ...schema, type }, value));
58 - }
59 -
60 - if (schemaType === undefined) {
61 - if (schema.properties) return isPlainObject(value);
62 - if (schema.items) return Array.isArray(value);
63 - return false;
64 - }
65 -
66 - switch (schemaType) {
67 - case 'array':
68 - return Array.isArray(value);
69 - case 'object':
70 - return isPlainObject(value);
71 - case 'string':
72 - return typeof value === 'string';
73 - case 'integer':
74 - return Number.isInteger(value);
75 - case 'number':
76 - return typeof value === 'number';
77 - case 'boolean':
78 - return typeof value === 'boolean';
79 - case 'null':
80 - return value === null;
81 - default:
82 - return false;
83 - }
84 -};
85 -
86 -const findSchemaVariantWithFileProperty = (
87 - schema: JSONSchemaProperty | undefined,
88 - property: 'file_uploadable' | 'file_downloadable',
89 - value: unknown
90 -): JSONSchemaProperty | undefined => {
91 - const candidates = getSchemaVariants(schema).filter(variant =>
92 - schemaHasFileProperty(variant, property)
93 - );
94 -
95 - return (
96 - candidates.find(candidate => jsonSchemaTypeMatchesValue(candidate, value)) ?? candidates[0]
97 - );
98 -};
99 -
51 /**
101 - * Recursively walks a runtime value and its matching JSON-Schema node,
102 - * uploading any string path whose schema node has `file_uploadable: true`.
103 - * The function returns a **new** value with all substitutions applied;
104 - * nothing is mutated in-place.
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 */
106 -const hydrateFiles = async (
57 +const stageFileValue = async (
58 value: unknown,
108 - schema: JSONSchemaProperty | undefined,
59 ctx: {
60 toolSlug: string;
61 toolkitSlug: string;
@@ -120,133 +70,85 @@ const hydrateFiles = async (
70 beforeFileUpload?: beforeFileUploadModifier;
71 }
72 ): Promise<unknown> => {
123 - // ──────────────────────────────────────────────────────────────────────────
124 - // 1. Direct file upload
125 - // ──────────────────────────────────────────────────────────────────────────
126 - if (schema?.file_uploadable) {
127 - // Upload only if the runtime value is a string (i.e., a local path) or blob
128 - if (typeof value !== 'string' && !(value instanceof File)) return value;
129 -
130 - const runBeforeFileUpload = async (
131 - path: string,
132 - source: 'path' | 'url' | 'file'
133 - ): Promise<string> => {
134 - if (!ctx.beforeFileUpload) {
135 - return path;
136 - }
137 - const out = await ctx.beforeFileUpload({
138 - path,
139 - source,
140 - toolSlug: ctx.toolSlug,
141 - toolkitSlug: ctx.toolkitSlug,
142 - });
143 - if (out === false) {
144 - throw new ComposioFileUploadAbortedError(
145 - 'File upload was aborted because beforeFileUpload returned false.'
146 - );
147 - }
148 - return out;
149 - };
150 -
151 - if (typeof value === 'string') {
152 - // Match the URL/local-path split used downstream in
153 - // getFileDataAfterUploadingToS3 so the hook sees the same categorisation.
154 - const source = isHttpUrl(value) ? 'url' : 'path';
155 - const pathOrUrl = await runBeforeFileUpload(value, source);
156 - logger.debug(`Uploading file "${pathOrUrl}"`);
157 - return getFileDataAfterUploadingToS3(pathOrUrl, {
158 - toolSlug: ctx.toolSlug,
159 - toolkitSlug: ctx.toolkitSlug,
160 - client: ctx.client,
161 - sensitiveFileUploadProtection: ctx.sensitiveFileUploadProtection,
162 - fileUploadPathDenySegments: ctx.fileUploadPathDenySegments,
163 - fileUploadAllowlist: ctx.fileUploadAllowlist,
164 - signal: ctx.signal,
165 - });
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 }
167 -
168 - // File — `path` is the filename only; a string return replaces it with a
169 - // local-path upload.
170 - if (ctx.beforeFileUpload) {
171 - const out = await ctx.beforeFileUpload({
172 - path: value.name,
173 - source: 'file',
174 - toolSlug: ctx.toolSlug,
175 - toolkitSlug: ctx.toolkitSlug,
176 - });
177 - if (out === false) {
178 - throw new ComposioFileUploadAbortedError(
179 - 'File upload was aborted because beforeFileUpload returned false.'
180 - );
181 - }
182 - if (typeof out === 'string' && out !== value.name) {
183 - logger.debug(`Uploading file from path "${out}" (replaced File: ${value.name})`);
184 - return getFileDataAfterUploadingToS3(out, {
185 - toolSlug: ctx.toolSlug,
186 - toolkitSlug: ctx.toolkitSlug,
187 - client: ctx.client,
188 - sensitiveFileUploadProtection: ctx.sensitiveFileUploadProtection,
189 - fileUploadPathDenySegments: ctx.fileUploadPathDenySegments,
190 - fileUploadAllowlist: ctx.fileUploadAllowlist,
191 - signal: ctx.signal,
192 - });
193 - }
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 }
195 - logger.debug(`Uploading file "${value.name}"`);
196 - // File/Blob values are not subject to the upload-dir allowlist.
197 - return getFileDataAfterUploadingToS3(value, {
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
207 - // ──────────────────────────────────────────────────────────────────────────
208 - // 2. Handle anyOf/oneOf/allOf — pick the file-bearing variant whose
209 - // JSON Schema shape matches the runtime value, then hydrate against it.
210 - //
211 - // We deliberately do NOT loop over every uploadable variant. With `oneOf`,
212 - // exactly one variant should apply at runtime, and applying multiple would
213 - // upload the same file once per variant — two presigned-URL round-trips and
214 - // two S3 PUTs for a two-variant `oneOf`. If no runtime shape matches, fall
215 - // back to the first file-bearing variant to preserve historical behavior.
216 - // ──────────────────────────────────────────────────────────────────────────
217 - const uploadableVariant = findSchemaVariantWithFileProperty(schema, 'file_uploadable', value);
218 - if (uploadableVariant) {
219 - return hydrateFiles(value, uploadableVariant, ctx);
220 - }
221 -
222 - // ──────────────────────────────────────────────────────────────────────────
223 - // 3. Object → traverse each property
224 - // ──────────────────────────────────────────────────────────────────────────
225 - if (schema?.type === 'object' && schema.properties && isPlainObject(value)) {
226 - const transformed: Record<string, unknown> = {};
227 -
228 - for (const [k, v] of Object.entries(value)) {
229 - transformed[k] = await hydrateFiles(v, schema.properties[k], ctx);
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 }
231 - return transformed;
232 - }
233 -
234 - // ──────────────────────────────────────────────────────────────────────────
235 - // 4. Array → traverse each item
236 - // ──────────────────────────────────────────────────────────────────────────
237 - if (schema?.type === 'array' && schema.items && Array.isArray(value)) {
238 - // `items` can be a single schema or an array of schemas; we handle both.
239 - const itemSchema = Array.isArray(schema.items) ? schema.items[0] : schema.items;
240 -
241 - return Promise.all(
242 - value.map(item => hydrateFiles(item, itemSchema as JSONSchemaProperty, ctx))
243 - );
141 }
245 -
246 - // ──────────────────────────────────────────────────────────────────────────
247 - // 5. Primitive or schema-less branch → return unchanged
248 - // ──────────────────────────────────────────────────────────────────────────
249 - return value;
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 /**
@@ -426,13 +328,15 @@ export class FileToolModifier {
328 try {
329 const newArgs = await withCancellation(
330 () =>
429 - hydrateFiles(args, resolveFileSchema(tool.inputParameters), {
430 - toolSlug,
431 - toolkitSlug,
432 - client: this.client,
433 - ...this.fileUploadPathOptions,
434 - signal,
435 - }),
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'] };
ts/packages/core/src/utils/modifiers/FileToolModifier.utils.neutral.ts
+151
@@ -116,6 +116,20 @@ export const schemaHasFileProperty = (
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
@@ -132,3 +146,140 @@ export const schemaHasFileUploadable = (schema: JSONSchemaProperty | undefined):
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 +/**
207 + * Picks the file-bearing `anyOf`/`oneOf`/`allOf` variant whose JSON Schema
208 + * shape matches the runtime value, falling back to the first file-bearing
209 + * variant to preserve historical behavior.
210 + */
211 +export const findSchemaVariantWithFileProperty = (
212 + schema: JSONSchemaProperty | undefined,
213 + property: 'file_uploadable' | 'file_downloadable',
214 + value: unknown
215 +): JSONSchemaProperty | undefined => {
216 + const candidates = getSchemaVariants(schema).filter(variant =>
217 + schemaHasFileProperty(variant, property)
218 + );
219 +
220 + return (
221 + candidates.find(candidate => jsonSchemaTypeMatchesValue(candidate, value)) ?? candidates[0]
222 + );
223 +};
224 +
225 +/**
226 + * Recursively walks a runtime value alongside its (already dereferenced)
227 + * JSON-Schema node and passes every value sitting at a `file_uploadable`
228 + * node through `leaf`. A leaf returning {@link DELETE_VALUE} is omitted from
229 + * its parent object/array. Returns a **new** value; nothing is mutated.
230 + *
231 + * Composed schemas are resolved to the single file-bearing variant whose
232 + * shape matches the value: with `oneOf`, exactly one variant should apply at
233 + * runtime, and applying several would stage the same file once per variant.
234 + */
235 +export const walkFileUploadableLeaves = async (
236 + value: unknown,
237 + schema: JSONSchemaProperty | undefined,
238 + leaf: (value: unknown) => Promise<unknown>
239 +): Promise<unknown> => {
240 + if (schema?.file_uploadable) {
241 + return leaf(value);
242 + }
243 +
244 + const uploadableVariant = findSchemaVariantWithFileProperty(schema, 'file_uploadable', value);
245 + if (uploadableVariant) {
246 + return walkFileUploadableLeaves(value, uploadableVariant, leaf);
247 + }
248 +
249 + if (schema?.type === 'object' && schema.properties && isPlainObject(value)) {
250 + const transformed: Record<string, unknown> = {};
251 + for (const [k, v] of Object.entries(value)) {
252 + const walked = await walkFileUploadableLeaves(v, schema.properties[k], leaf);
253 + if (walked !== DELETE_VALUE) transformed[k] = walked;
254 + }
255 + return transformed;
256 + }
257 +
258 + if (schema?.type === 'array' && schema.items && Array.isArray(value)) {
259 + // `items` can be a single schema or an array of schemas; we handle both.
260 + const itemSchema = Array.isArray(schema.items) ? schema.items[0] : schema.items;
261 + const walked = await Promise.all(
262 + value.map(item => walkFileUploadableLeaves(item, itemSchema as JSONSchemaProperty, leaf))
263 + );
264 + return walked.filter(item => item !== DELETE_VALUE);
265 + }
266 +
267 + return value;
268 +};
269 +
270 +/**
271 + * Omits `''` at `file_uploadable` leaves of `args` without uploading
272 + * anything. This is the schema-aware half of the upload modifier that needs
273 + * no filesystem access, so it also runs when automatic upload is disabled:
274 + * an empty file value is never a valid staged descriptor and the backend
275 + * would reject it (https://github.com/ComposioHQ/composio/issues/4233).
276 + * Any other value — a local path, a staged descriptor, a list — is
277 + * forwarded untouched.
278 + */
279 +export const dropEmptyFileUploads = (
280 + args: Record<string, unknown>,
281 + schema: JSONSchemaProperty | undefined
282 +): Promise<unknown> =>
283 + walkFileUploadableLeaves(args, schema, async value =>
284 + isEmptyFileValue(value) ? DELETE_VALUE : value
285 + );
ts/packages/core/test/tools/fileModifiers.test.ts
+91
@@ -311,6 +311,55 @@ describe('FileToolModifier', () => {
311 availableVersions: ['20251201_01'],
312 };
313
314 + it('drops empty file values instead of uploading them (issue #4233)', async () => {
315 + const fileUploadable = {
316 + type: 'object' as const,
317 + title: 'FileUploadable',
318 + file_uploadable: true,
319 + properties: {
320 + name: { type: 'string' as const },
321 + mimetype: { type: 'string' as const },
322 + s3key: { type: 'string' as const },
323 + },
324 + required: ['name', 'mimetype', 's3key'],
325 + };
326 + const gmailLikeTool: Tool = {
327 + ...mockTool,
328 + inputParameters: {
329 + type: 'object',
330 + properties: {
331 + subject: { type: 'string' },
332 + attachment: { anyOf: [fileUploadable, { type: 'array', items: fileUploadable }] },
333 + extra: { type: 'array', items: fileUploadable },
334 + thread_id: { type: 'string' },
335 + },
336 + },
337 + };
338 + const staged = { name: 'a.txt', mimetype: 'text/plain', s3key: 'k' };
339 +
340 + const result = await fileToolModifier.fileUploadModifier(gmailLikeTool, {
341 + toolSlug: 'test-tool',
342 + toolkitSlug: 'test-toolkit',
343 + params: {
344 + arguments: {
345 + subject: 'Test',
346 + attachment: '',
347 + extra: ['', staged],
348 + thread_id: '',
349 + },
350 + userId: 'test-user',
351 + },
352 + });
353 +
354 + expect(fileUtils.getFileDataAfterUploadingToS3).not.toHaveBeenCalled();
355 + expect(result.arguments).toEqual({
356 + subject: 'Test',
357 + extra: [staged],
358 + // non-file empty strings are not the walker's business
359 + thread_id: '',
360 + });
361 + });
362 +
363 it('should upload file for file_uploadable parameters', async () => {
364 const mockFileData = {
365 name: 'file.txt',
@@ -2035,6 +2084,48 @@ describe('Tools with dangerouslyAllowAutoUploadDownloadFiles', () => {
2084 );
2085 });
2086
2087 + it('omits empty file values from the request when auto-upload is off (issue #4233)', async () => {
2088 + vi.spyOn(context.tools, 'getRawComposioToolBySlug').mockResolvedValue(mockToolWithFileUpload);
2089 +
2090 + await context.tools.execute('COMPOSIO_TOOL', {
2091 + arguments: { file: '', text: 'keep' },
2092 + userId: 'test-user',
2093 + dangerouslySkipVersionCheck: true,
2094 + });
2095 +
2096 + expect(fileUtils.getFileDataAfterUploadingToS3).not.toHaveBeenCalled();
2097 + expect(mockClient.tools.execute.mock.calls[0]?.[1]?.arguments).toEqual({ text: 'keep' });
2098 + });
2099 +
2100 + it('omits empty file values reachable only through a $ref (issue #4233)', async () => {
2101 + // Composio toolkits express file flags through `$ref`/`$defs`, so the
2102 + // cheap "does this tool take a file?" gate has to see through the
2103 + // indirection or the fix never fires for a real tool.
2104 + vi.spyOn(context.tools, 'getRawComposioToolBySlug').mockResolvedValue({
2105 + ...mockToolWithFileUpload,
2106 + inputParameters: {
2107 + type: 'object',
2108 + properties: { file: { $ref: '#/$defs/Attachment' }, text: { type: 'string' } },
2109 + $defs: {
2110 + Attachment: {
2111 + type: 'object',
2112 + file_uploadable: true,
2113 + properties: { name: { type: 'string' }, s3key: { type: 'string' } },
2114 + },
2115 + },
2116 + },
2117 + });
2118 +
2119 + await context.tools.execute('COMPOSIO_TOOL', {
2120 + arguments: { file: '', text: 'keep' },
2121 + userId: 'test-user',
2122 + dangerouslySkipVersionCheck: true,
2123 + });
2124 +
2125 + expect(fileUtils.getFileDataAfterUploadingToS3).not.toHaveBeenCalled();
2126 + expect(mockClient.tools.execute.mock.calls[0]?.[1]?.arguments).toEqual({ text: 'keep' });
2127 + });
2128 +
2129 it('warns once per tool when auto-upload is off and the tool has a file-uploadable input', async () => {
2130 const warnSpy = vi.spyOn((await import('../../src/utils/logger')).default, 'warn');
2131 warnSpy.mockImplementation(() => {}); // silence the log in test output