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