Skip to content

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

jkomynofe66cbeb77ce
diff --git a/.changeset/drop-empty-file-uploads.md b/.changeset/drop-empty-file-uploads.md
new file mode 100644
index 000000000..4f80d84ac
--- /dev/null
+++ b/.changeset/drop-empty-file-uploads.md
@@ -0,0 +1,5 @@
+---
+'@composio/core': patch
+---
+
+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.
diff --git a/python/composio/core/models/_files.py b/python/composio/core/models/_files.py
index 2dbaf3e61..39de3b2b5 100644
--- a/python/composio/core/models/_files.py
+++ b/python/composio/core/models/_files.py
@@ -1,5 +1,6 @@
from __future__ import annotations
+import functools
import hashlib
import os
import typing as t
@@ -1039,13 +1040,23 @@ class FileHelper(WithLogger):
value=value,
)
+ @staticmethod
+ def _drop_empty_file_value(value: t.Any) -> t.Any:
+ """Leaf handler: ``None``/``""`` at a file leaf mean "no file".
+
+ Neither is a staged ``{name, mimetype, s3key}`` descriptor, so the
+ backend rejects them with a validation error while callers (and the
+ playground UI) mean "absent". The walker omits the key instead.
+ """
+ return _DELETE_VALUE if value is None or value == "" else value
+
def _upload_file_value(
self,
value: t.Any,
tool: Tool,
before_file_upload: t.Optional[BeforeFileUpload],
) -> t.Any:
- if value is None or value == "":
+ if self._drop_empty_file_value(value) is _DELETE_VALUE:
return _DELETE_VALUE
return FileUploadable.from_path(
@@ -1063,20 +1074,18 @@ class FileHelper(WithLogger):
self,
value: t.Any,
schema: t.Optional[t.Dict],
- tool: Tool,
- *,
- before_file_upload: t.Optional[BeforeFileUpload] = None,
+ leaf: t.Callable[[t.Any], t.Any],
) -> t.Any:
- """Return ``value`` with file-uploadable leaves staged for execution."""
+ """Return ``value`` with every ``file_uploadable`` leaf passed through ``leaf``.
+
+ A leaf may return ``_DELETE_VALUE`` to omit the key/item from its
+ parent container.
+ """
if not isinstance(schema, dict):
return value
if schema.get("file_uploadable", False):
- return self._upload_file_value(
- value=value,
- tool=tool,
- before_file_upload=before_file_upload,
- )
+ return leaf(value)
uploadable_variant = self._find_uploadable_schema_variant(
schema=schema,
@@ -1086,8 +1095,7 @@ class FileHelper(WithLogger):
return self._substitute_file_upload_value(
value=value,
schema=uploadable_variant,
- tool=tool,
- before_file_upload=before_file_upload,
+ leaf=leaf,
)
if isinstance(value, dict) and "properties" in schema:
@@ -1098,8 +1106,7 @@ class FileHelper(WithLogger):
processed_item = self._substitute_file_upload_value(
value=item,
schema=item_schema,
- tool=tool,
- before_file_upload=before_file_upload,
+ leaf=leaf,
)
if processed_item is not _DELETE_VALUE:
processed[key] = processed_item
@@ -1115,8 +1122,7 @@ class FileHelper(WithLogger):
processed_item = self._substitute_file_upload_value(
value=item,
schema=items_schema,
- tool=tool,
- before_file_upload=before_file_upload,
+ leaf=leaf,
)
if processed_item is not _DELETE_VALUE:
processed_items.append(processed_item)
@@ -1131,12 +1137,19 @@ class FileHelper(WithLogger):
request: t.Dict,
*,
before_file_upload: t.Optional[BeforeFileUpload] = None,
+ leaf: t.Optional[t.Callable[[t.Any], t.Any]] = None,
) -> t.Dict:
+ if leaf is None:
+ leaf = functools.partial(
+ self._upload_file_value,
+ tool=tool,
+ before_file_upload=before_file_upload,
+ )
+
processed = self._substitute_file_upload_value(
value=request,
schema=schema,
- tool=tool,
- before_file_upload=before_file_upload,
+ leaf=leaf,
)
if processed is request:
return request
@@ -1177,6 +1190,32 @@ class FileHelper(WithLogger):
before_file_upload=before_file_upload,
)
+ def drop_empty_file_uploads(self, tool: Tool, request: t.Dict) -> t.Dict:
+ """Omit ``None``/``""`` at ``file_uploadable`` leaves without uploading.
+
+ This is the half of :meth:`substitute_file_uploads` that needs no
+ filesystem access, so it runs even when automatic upload is disabled:
+ an empty file value is never a valid staged descriptor and the backend
+ would reject it (issue #4233). Any other value -- a local path, a
+ staged descriptor, a list -- is forwarded untouched. Same mutation
+ contract as :meth:`substitute_file_uploads`.
+ """
+ schema = dereference_json_schema(
+ tool.input_parameters, on_unresolved="sentinel"
+ )
+ # Every execution takes this path by default, so leave requests for
+ # tools without a file input completely alone (identity included)
+ # instead of rebuilding their nested dicts.
+ if not self._file_uploadable(schema):
+ return request
+
+ return self._substitute_file_uploads_recursively(
+ tool=tool,
+ schema=schema,
+ request=request,
+ leaf=self._drop_empty_file_value,
+ )
+
def _is_file_downloadable(self, schema: t.Dict) -> bool:
"""Check if a schema has file_downloadable property."""
return self._has_file_property(schema, "file_downloadable")
diff --git a/python/composio/core/models/tools.py b/python/composio/core/models/tools.py
index ba50b4642..1fabec06f 100644
--- a/python/composio/core/models/tools.py
+++ b/python/composio/core/models/tools.py
@@ -515,6 +515,10 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
request=arguments,
before_file_upload=bfu,
)
+ else:
+ arguments = self._file_helper.drop_empty_file_uploads(
+ tool=tool, request=arguments
+ )
toolkit_slug = _toolkit_slug(tool, "composio")
@@ -676,6 +680,12 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
request=arguments,
before_file_upload=bfu,
)
+ else:
+ # Auto-upload is opt-in, but "no file" must still be sent as an
+ # omitted key rather than ``""``/``None`` (issue #4233).
+ arguments = self._file_helper.drop_empty_file_uploads(
+ tool=tool, request=arguments
+ )
if modifiers is not None:
type_before_exec: t.Literal["before_execute"] = "before_execute"
diff --git a/python/tests/test_auto_upload_download_files.py b/python/tests/test_auto_upload_download_files.py
index 6f16118f4..0b3212593 100644
--- a/python/tests/test_auto_upload_download_files.py
+++ b/python/tests/test_auto_upload_download_files.py
@@ -456,6 +456,72 @@ class TestAutoUploadDownloadFilesDisabled:
mock_substitute.assert_not_called()
+ def test_execute_drops_empty_file_values_when_disabled(
+ self, mock_client, mock_provider
+ ):
+ """Issue #4233: with auto-upload off, ``attachment: ""`` must be
+ omitted from the request instead of forwarded to the backend, while a
+ real value is forwarded as-is (not uploaded)."""
+ tools = Tools(
+ client=mock_client,
+ provider=mock_provider,
+ toolkit_versions={"gmail": "20251201_01"},
+ )
+
+ file_uploadable = {
+ "type": "object",
+ "file_uploadable": True,
+ "properties": {
+ "name": {"type": "string"},
+ "mimetype": {"type": "string"},
+ "s3key": {"type": "string"},
+ },
+ }
+ mock_tool = create_mock_tool(
+ slug="GMAIL_CREATE_DRAFT",
+ toolkit_slug="gmail",
+ input_parameters={
+ "type": "object",
+ "properties": {
+ "subject": {"type": "string"},
+ "attachment": {
+ "anyOf": [
+ file_uploadable,
+ {"type": "array", "items": file_uploadable},
+ {"type": "null"},
+ ]
+ },
+ },
+ },
+ )
+ mock_execute_response = Mock()
+ mock_execute_response.model_dump.return_value = {
+ "data": {},
+ "error": None,
+ "successful": True,
+ }
+ mock_client.tools.execute.return_value = mock_execute_response
+
+ with patch.object(
+ tools, "get_raw_composio_tool_by_slug", return_value=mock_tool
+ ):
+ for value, expected in (
+ ("", {"subject": "Test"}),
+ (None, {"subject": "Test"}),
+ (
+ "/path/to/file.txt",
+ {"subject": "Test", "attachment": "/path/to/file.txt"},
+ ),
+ ):
+ mock_client.tools.execute.reset_mock()
+ tools.execute(
+ slug="GMAIL_CREATE_DRAFT",
+ arguments={"subject": "Test", "attachment": value},
+ dangerously_skip_version_check=True,
+ )
+ sent = mock_client.tools.execute.call_args.kwargs["arguments"]
+ assert sent == expected, value
+
def test_execute_skips_file_downloads_when_disabled(
self, mock_client, mock_provider
):
diff --git a/python/tests/test_files.py b/python/tests/test_files.py
index 939751205..fbaa0889a 100644
--- a/python/tests/test_files.py
+++ b/python/tests/test_files.py
@@ -779,6 +779,72 @@ class TestFileUploadSubstitutionWithUnionTypes:
# None/empty values should be removed
assert "fileInput" not in result
+ def test_drop_empty_file_uploads_omits_empty_leaves_without_uploading(
+ self, file_helper, mock_tool
+ ):
+ """Issue #4233: ``""``/``None`` at a file leaf mean "no file" even when
+ auto-upload is off, while any other value is forwarded untouched."""
+ file_uploadable = {
+ "type": "object",
+ "file_uploadable": True,
+ "title": "FileUploadable",
+ "properties": {
+ "name": {"type": "string"},
+ "mimetype": {"type": "string"},
+ "s3key": {"type": "string"},
+ },
+ "required": ["name", "mimetype", "s3key"],
+ }
+ mock_tool.input_parameters = {
+ "type": "object",
+ "properties": {
+ "subject": {"type": "string"},
+ "attachment": {
+ "anyOf": [
+ file_uploadable,
+ {"type": "array", "items": file_uploadable},
+ {"type": "null"},
+ ],
+ "default": None,
+ },
+ "extra": {
+ "anyOf": [
+ {"type": "array", "items": file_uploadable},
+ {"type": "null"},
+ ]
+ },
+ "nested": {
+ "type": "object",
+ "properties": {"file": {"$ref": "#/$defs/F"}},
+ },
+ "thread_id": {"type": "string"},
+ },
+ "$defs": {"F": file_uploadable},
+ }
+ staged = {"name": "a.txt", "mimetype": "text/plain", "s3key": "k"}
+ request = {
+ "subject": "Test",
+ "attachment": "",
+ "extra": [None, "", staged, "/tmp/keep.txt"],
+ "nested": {"file": None},
+ "thread_id": "",
+ }
+
+ with patch.object(FileUploadable, "from_path") as from_path:
+ result = file_helper.drop_empty_file_uploads(
+ tool=mock_tool, request=request
+ )
+
+ from_path.assert_not_called()
+ assert result is request
+ assert result == {
+ "subject": "Test",
+ "extra": [staged, "/tmp/keep.txt"],
+ "nested": {},
+ # non-file empty strings are not the walker's business
+ "thread_id": "",
+ }
+
def test_substitute_upload_empty_string_in_anyof(self, file_helper, mock_tool):
"""Test that empty string values in anyOf with file_uploadable are handled."""
mock_tool.input_parameters = {
diff --git a/ts/packages/core/src/models/Tools.ts b/ts/packages/core/src/models/Tools.ts
index 8bc2dc48b..d1dfe48f4 100644
--- a/ts/packages/core/src/models/Tools.ts
+++ b/ts/packages/core/src/models/Tools.ts
@@ -54,7 +54,11 @@ import { handleToolExecutionError } from '../errors/ToolErrors';
import type { SessionExecuteParams } from '@composio/client/resources/tool-router/session/session.mjs';
import { CONFIG_DEFAULTS } from '../utils/config-defaults';
import { resolveEffectiveUploadAllowlist } from '../utils/fileDirs';
-import { schemaHasFileUploadable } from '../utils/modifiers/FileToolModifier.utils.neutral';
+import {
+ dropEmptyFileUploads,
+ schemaHasFileUploadable,
+} from '../utils/modifiers/FileToolModifier.utils.neutral';
+import { dereferenceJsonSchema } from '../utils/jsonSchema';
import { ComposioRequestOptions } from '../types/requestOptions.types';
import { withCancellation } from '../utils/cancellation';
import { ComposioRequestCancelledError } from '../errors/SDKErrors';
@@ -284,26 +288,38 @@ export class Tools<
if (requestOptions?.signal?.aborted) {
throw new ComposioRequestCancelledError();
}
- } else if (
- schemaHasFileUploadable(tool.inputParameters) &&
- !this.warnedAutoUploadDisabledForTool.has(toolSlug)
- ) {
- // With auto-upload off, the raw `{ name, mimetype, s3key }` shape is
- // what the LLM / caller sees on `tool.inputParameters`. LLMs can't
- // produce a valid `s3key` and will hallucinate one, which then fails
- // at the staging-lookup step on the backend. Nudge the caller toward
- // manual staging or opting into auto-upload.
- this.warnedAutoUploadDisabledForTool.add(toolSlug);
- logger.warn(
- `Tool "${toolSlug}" (toolkit "${toolkitSlug}") has a file-uploadable input, but ` +
- `\`dangerouslyAllowAutoUploadDownloadFiles\` is disabled. The SDK will forward ` +
- `the file argument as-is; if it isn't already a staged ` +
- `{ name, mimetype, s3key } descriptor, the backend will reject the call. Either:\n` +
- ` 1) Stage the file yourself: \`const f = await composio.files.upload({ file, toolSlug, toolkitSlug }); ` +
- `await composio.tools.execute('${toolSlug}', { userId, arguments: { <fileField>: f } })\`, or\n` +
- ` 2) Enable auto-upload with a scoped allowlist: ` +
- `\`new Composio({ dangerouslyAllowAutoUploadDownloadFiles: true, fileUploadDirs: ['/safe/dir'] })\`.`
- );
+ } else if (tool.inputParameters && schemaHasFileUploadable(tool.inputParameters)) {
+ // Auto-upload is opt-in, but "no file" must still be sent as an
+ // omitted key rather than `''`, which the backend rejects
+ // (https://github.com/ComposioHQ/composio/issues/4233).
+ if (modifiedParams.arguments) {
+ modifiedParams = {
+ ...modifiedParams,
+ arguments: (await dropEmptyFileUploads(
+ modifiedParams.arguments,
+ dereferenceJsonSchema(tool.inputParameters, { onUnresolved: 'sentinel' })
+ )) as ToolExecuteParams['arguments'],
+ };
+ }
+
+ if (!this.warnedAutoUploadDisabledForTool.has(toolSlug)) {
+ // With auto-upload off, the raw `{ name, mimetype, s3key }` shape is
+ // what the LLM / caller sees on `tool.inputParameters`. LLMs can't
+ // produce a valid `s3key` and will hallucinate one, which then fails
+ // at the staging-lookup step on the backend. Nudge the caller toward
+ // manual staging or opting into auto-upload.
+ this.warnedAutoUploadDisabledForTool.add(toolSlug);
+ logger.warn(
+ `Tool "${toolSlug}" (toolkit "${toolkitSlug}") has a file-uploadable input, but ` +
+ `\`dangerouslyAllowAutoUploadDownloadFiles\` is disabled. The SDK will forward ` +
+ `the file argument as-is; if it isn't already a staged ` +
+ `{ name, mimetype, s3key } descriptor, the backend will reject the call. Either:\n` +
+ ` 1) Stage the file yourself: \`const f = await composio.files.upload({ file, toolSlug, toolkitSlug }); ` +
+ `await composio.tools.execute('${toolSlug}', { userId, arguments: { <fileField>: f } })\`, or\n` +
+ ` 2) Enable auto-upload with a scoped allowlist: ` +
+ `\`new Composio({ dangerouslyAllowAutoUploadDownloadFiles: true, fileUploadDirs: ['/safe/dir'] })\`.`
+ );
+ }
}
// apply the before execute modifiers
if (modifiers?.beforeExecute) {
@@ -1308,7 +1324,7 @@ export class Tools<
* @deprecated The `customConnectionData` proxy param is deprecated and will be
* removed in a future release. Use `customAuthParams` instead.
*/
- // @ts-ignore
+ // @ts-expect-error
custom_connection_data: toolProxyParams.data.customConnectionData,
} as ComposioToolProxyParams;
return withCancellation(
diff --git a/ts/packages/core/src/utils/modifiers/FileToolModifier.node.ts b/ts/packages/core/src/utils/modifiers/FileToolModifier.node.ts
index fb0e24386..6b5357466 100644
--- a/ts/packages/core/src/utils/modifiers/FileToolModifier.node.ts
+++ b/ts/packages/core/src/utils/modifiers/FileToolModifier.node.ts
@@ -22,9 +22,13 @@ import {
type GetFileDataAfterUploadingToS3Options,
} from '../fileUtils.node';
import {
+ DELETE_VALUE,
+ findSchemaVariantWithFileProperty,
+ getSchemaVariants,
+ isEmptyFileValue,
isPlainObject,
transformProperties,
- schemaHasFileProperty,
+ walkFileUploadableLeaves,
} from './FileToolModifier.utils.neutral';
import { dereferenceJsonSchema } from '../jsonSchema';
import { withCancellation } from '../cancellation';
@@ -44,68 +48,14 @@ const resolveFileSchema = <Schema extends JSONSchemaProperty>(
): Schema | undefined =>
schema ? dereferenceJsonSchema(schema, { onUnresolved: 'sentinel' }) : schema;
-const getSchemaVariants = (schema: JSONSchemaProperty | undefined): JSONSchemaProperty[] => [
- ...(schema?.anyOf ?? []),
- ...(schema?.oneOf ?? []),
- ...(schema?.allOf ?? []),
-];
-
-const jsonSchemaTypeMatchesValue = (schema: JSONSchemaProperty, value: unknown): boolean => {
- const schemaType = schema.type;
-
- if (Array.isArray(schemaType)) {
- return schemaType.some(type => jsonSchemaTypeMatchesValue({ ...schema, type }, value));
- }
-
- if (schemaType === undefined) {
- if (schema.properties) return isPlainObject(value);
- if (schema.items) return Array.isArray(value);
- return false;
- }
-
- switch (schemaType) {
- case 'array':
- return Array.isArray(value);
- case 'object':
- return isPlainObject(value);
- case 'string':
- return typeof value === 'string';
- case 'integer':
- return Number.isInteger(value);
- case 'number':
- return typeof value === 'number';
- case 'boolean':
- return typeof value === 'boolean';
- case 'null':
- return value === null;
- default:
- return false;
- }
-};
-
-const findSchemaVariantWithFileProperty = (
- schema: JSONSchemaProperty | undefined,
- property: 'file_uploadable' | 'file_downloadable',
- value: unknown
-): JSONSchemaProperty | undefined => {
- const candidates = getSchemaVariants(schema).filter(variant =>
- schemaHasFileProperty(variant, property)
- );
-
- return (
- candidates.find(candidate => jsonSchemaTypeMatchesValue(candidate, value)) ?? candidates[0]
- );
-};
-
/**
- * Recursively walks a runtime value and its matching JSON-Schema node,
- * uploading any string path whose schema node has `file_uploadable: true`.
- * The function returns a **new** value with all substitutions applied;
- * nothing is mutated in-place.
+ * Stages one `file_uploadable` leaf: a local path / URL string or a `File`
+ * is uploaded to S3 and replaced by its `{ name, mimetype, s3key }`
+ * descriptor; `''` means "no file" and is dropped from the request;
+ * anything else (e.g. an already-staged descriptor) passes through.
*/
-const hydrateFiles = async (
+const stageFileValue = async (
value: unknown,
- schema: JSONSchemaProperty | undefined,
ctx: {
toolSlug: string;
toolkitSlug: string;
@@ -120,133 +70,85 @@ const hydrateFiles = async (
beforeFileUpload?: beforeFileUploadModifier;
}
): Promise<unknown> => {
- // ──────────────────────────────────────────────────────────────────────────
- // 1. Direct file upload
- // ──────────────────────────────────────────────────────────────────────────
- if (schema?.file_uploadable) {
- // Upload only if the runtime value is a string (i.e., a local path) or blob
- if (typeof value !== 'string' && !(value instanceof File)) return value;
-
- const runBeforeFileUpload = async (
- path: string,
- source: 'path' | 'url' | 'file'
- ): Promise<string> => {
- if (!ctx.beforeFileUpload) {
- return path;
- }
- const out = await ctx.beforeFileUpload({
- path,
- source,
- toolSlug: ctx.toolSlug,
- toolkitSlug: ctx.toolkitSlug,
- });
- if (out === false) {
- throw new ComposioFileUploadAbortedError(
- 'File upload was aborted because beforeFileUpload returned false.'
- );
- }
- return out;
- };
-
- if (typeof value === 'string') {
- // Match the URL/local-path split used downstream in
- // getFileDataAfterUploadingToS3 so the hook sees the same categorisation.
- const source = isHttpUrl(value) ? 'url' : 'path';
- const pathOrUrl = await runBeforeFileUpload(value, source);
- logger.debug(`Uploading file "${pathOrUrl}"`);
- return getFileDataAfterUploadingToS3(pathOrUrl, {
- toolSlug: ctx.toolSlug,
- toolkitSlug: ctx.toolkitSlug,
- client: ctx.client,
- sensitiveFileUploadProtection: ctx.sensitiveFileUploadProtection,
- fileUploadPathDenySegments: ctx.fileUploadPathDenySegments,
- fileUploadAllowlist: ctx.fileUploadAllowlist,
- signal: ctx.signal,
- });
+ if (isEmptyFileValue(value)) return DELETE_VALUE;
+ // Upload only if the runtime value is a string (i.e., a local path) or blob
+ if (typeof value !== 'string' && !(value instanceof File)) return value;
+
+ const runBeforeFileUpload = async (
+ path: string,
+ source: 'path' | 'url' | 'file'
+ ): Promise<string> => {
+ if (!ctx.beforeFileUpload) {
+ return path;
}
-
- // File — `path` is the filename only; a string return replaces it with a
- // local-path upload.
- if (ctx.beforeFileUpload) {
- const out = await ctx.beforeFileUpload({
- path: value.name,
- source: 'file',
- toolSlug: ctx.toolSlug,
- toolkitSlug: ctx.toolkitSlug,
- });
- if (out === false) {
- throw new ComposioFileUploadAbortedError(
- 'File upload was aborted because beforeFileUpload returned false.'
- );
- }
- if (typeof out === 'string' && out !== value.name) {
- logger.debug(`Uploading file from path "${out}" (replaced File: ${value.name})`);
- return getFileDataAfterUploadingToS3(out, {
- toolSlug: ctx.toolSlug,
- toolkitSlug: ctx.toolkitSlug,
- client: ctx.client,
- sensitiveFileUploadProtection: ctx.sensitiveFileUploadProtection,
- fileUploadPathDenySegments: ctx.fileUploadPathDenySegments,
- fileUploadAllowlist: ctx.fileUploadAllowlist,
- signal: ctx.signal,
- });
- }
+ const out = await ctx.beforeFileUpload({
+ path,
+ source,
+ toolSlug: ctx.toolSlug,
+ toolkitSlug: ctx.toolkitSlug,
+ });
+ if (out === false) {
+ throw new ComposioFileUploadAbortedError(
+ 'File upload was aborted because beforeFileUpload returned false.'
+ );
}
- logger.debug(`Uploading file "${value.name}"`);
- // File/Blob values are not subject to the upload-dir allowlist.
- return getFileDataAfterUploadingToS3(value, {
+ return out;
+ };
+
+ if (typeof value === 'string') {
+ // Match the URL/local-path split used downstream in
+ // getFileDataAfterUploadingToS3 so the hook sees the same categorisation.
+ const source = isHttpUrl(value) ? 'url' : 'path';
+ const pathOrUrl = await runBeforeFileUpload(value, source);
+ logger.debug(`Uploading file "${pathOrUrl}"`);
+ return getFileDataAfterUploadingToS3(pathOrUrl, {
toolSlug: ctx.toolSlug,
toolkitSlug: ctx.toolkitSlug,
client: ctx.client,
sensitiveFileUploadProtection: ctx.sensitiveFileUploadProtection,
fileUploadPathDenySegments: ctx.fileUploadPathDenySegments,
+ fileUploadAllowlist: ctx.fileUploadAllowlist,
signal: ctx.signal,
});
}
- // ──────────────────────────────────────────────────────────────────────────
- // 2. Handle anyOf/oneOf/allOf — pick the file-bearing variant whose
- // JSON Schema shape matches the runtime value, then hydrate against it.
- //
- // We deliberately do NOT loop over every uploadable variant. With `oneOf`,
- // exactly one variant should apply at runtime, and applying multiple would
- // upload the same file once per variant — two presigned-URL round-trips and
- // two S3 PUTs for a two-variant `oneOf`. If no runtime shape matches, fall
- // back to the first file-bearing variant to preserve historical behavior.
- // ──────────────────────────────────────────────────────────────────────────
- const uploadableVariant = findSchemaVariantWithFileProperty(schema, 'file_uploadable', value);
- if (uploadableVariant) {
- return hydrateFiles(value, uploadableVariant, ctx);
- }
-
- // ──────────────────────────────────────────────────────────────────────────
- // 3. Object → traverse each property
- // ──────────────────────────────────────────────────────────────────────────
- if (schema?.type === 'object' && schema.properties && isPlainObject(value)) {
- const transformed: Record<string, unknown> = {};
-
- for (const [k, v] of Object.entries(value)) {
- transformed[k] = await hydrateFiles(v, schema.properties[k], ctx);
+ // File — `path` is the filename only; a string return replaces it with a
+ // local-path upload.
+ if (ctx.beforeFileUpload) {
+ const out = await ctx.beforeFileUpload({
+ path: value.name,
+ source: 'file',
+ toolSlug: ctx.toolSlug,
+ toolkitSlug: ctx.toolkitSlug,
+ });
+ if (out === false) {
+ throw new ComposioFileUploadAbortedError(
+ 'File upload was aborted because beforeFileUpload returned false.'
+ );
+ }
+ if (typeof out === 'string' && out !== value.name) {
+ logger.debug(`Uploading file from path "${out}" (replaced File: ${value.name})`);
+ return getFileDataAfterUploadingToS3(out, {
+ toolSlug: ctx.toolSlug,
+ toolkitSlug: ctx.toolkitSlug,
+ client: ctx.client,
+ sensitiveFileUploadProtection: ctx.sensitiveFileUploadProtection,
+ fileUploadPathDenySegments: ctx.fileUploadPathDenySegments,
+ fileUploadAllowlist: ctx.fileUploadAllowlist,
+ signal: ctx.signal,
+ });
}
- return transformed;
- }
-
- // ──────────────────────────────────────────────────────────────────────────
- // 4. Array → traverse each item
- // ──────────────────────────────────────────────────────────────────────────
- if (schema?.type === 'array' && schema.items && Array.isArray(value)) {
- // `items` can be a single schema or an array of schemas; we handle both.
- const itemSchema = Array.isArray(schema.items) ? schema.items[0] : schema.items;
-
- return Promise.all(
- value.map(item => hydrateFiles(item, itemSchema as JSONSchemaProperty, ctx))
- );
}
-
- // ──────────────────────────────────────────────────────────────────────────
- // 5. Primitive or schema-less branch → return unchanged
- // ──────────────────────────────────────────────────────────────────────────
- return value;
+ logger.debug(`Uploading file "${value.name}"`);
+ // File/Blob values are not subject to the upload-dir allowlist.
+ return getFileDataAfterUploadingToS3(value, {
+ toolSlug: ctx.toolSlug,
+ toolkitSlug: ctx.toolkitSlug,
+ client: ctx.client,
+ sensitiveFileUploadProtection: ctx.sensitiveFileUploadProtection,
+ fileUploadPathDenySegments: ctx.fileUploadPathDenySegments,
+ signal: ctx.signal,
+ });
};
/**
@@ -426,13 +328,15 @@ export class FileToolModifier {
try {
const newArgs = await withCancellation(
() =>
- hydrateFiles(args, resolveFileSchema(tool.inputParameters), {
- toolSlug,
- toolkitSlug,
- client: this.client,
- ...this.fileUploadPathOptions,
- signal,
- }),
+ walkFileUploadableLeaves(args, resolveFileSchema(tool.inputParameters), value =>
+ stageFileValue(value, {
+ toolSlug,
+ toolkitSlug,
+ client: this.client,
+ ...this.fileUploadPathOptions,
+ signal,
+ })
+ ),
signal
);
return { ...params, arguments: newArgs as ToolExecuteParams['arguments'] };
diff --git a/ts/packages/core/src/utils/modifiers/FileToolModifier.utils.neutral.ts b/ts/packages/core/src/utils/modifiers/FileToolModifier.utils.neutral.ts
index 595331de0..d64e3fcf8 100644
--- a/ts/packages/core/src/utils/modifiers/FileToolModifier.utils.neutral.ts
+++ b/ts/packages/core/src/utils/modifiers/FileToolModifier.utils.neutral.ts
@@ -116,6 +116,20 @@ export const schemaHasFileProperty = (
}
}
+ // Check `$ref` targets. Composio toolkits routinely express file flags
+ // through a `$ref`/`$defs` indirection (e.g. GMAIL_GET_ATTACHMENT), and
+ // this predicate is the cheap gate that decides whether a schema is worth
+ // dereferencing at all — without this it answers `false` for every
+ // ref-based schema. Callers walk the *dereferenced* schema, where
+ // `dereferenceJsonSchema` has already stripped these blocks, so an unused
+ // `$defs` entry can only cost a redundant walk, never a wrong upload.
+ for (const definitions of [schema.$defs, schema.definitions]) {
+ if (!definitions) continue;
+ for (const definition of Object.values(definitions)) {
+ if (schemaHasFileProperty(definition, property)) return true;
+ }
+ }
+
return false;
};
@@ -132,3 +146,140 @@ export const schemaHasFileUploadable = (schema: JSONSchemaProperty | undefined):
export const schemaHasFileDownloadable = (schema: JSONSchemaProperty | undefined): boolean => {
return schemaHasFileProperty(schema, 'file_downloadable');
};
+
+/**
+ * Sentinel a leaf handler returns to have {@link walkFileUploadableLeaves}
+ * omit that key/item from its parent container. `''` and `null` are legal
+ * payload values, so neither can double as "remove this".
+ */
+export const DELETE_VALUE: unique symbol = Symbol('composio.delete-value');
+
+/**
+ * `''` at a `file_uploadable` leaf means "no file": it is never a staged
+ * `{ name, mimetype, s3key }` descriptor, so the backend rejects it with a
+ * validation error, while callers (and the playground UI) mean "absent". The
+ * walker omits the key instead. `null` is left alone — schemas with a `null`
+ * variant accept it, and the backend reports the mismatch otherwise.
+ */
+export const isEmptyFileValue = (value: unknown): boolean => value === '';
+
+export const getSchemaVariants = (schema: JSONSchemaProperty | undefined): JSONSchemaProperty[] => [
+ ...(schema?.anyOf ?? []),
+ ...(schema?.oneOf ?? []),
+ ...(schema?.allOf ?? []),
+];
+
+/** Best-effort runtime shape match for selecting composed schema variants. */
+export const jsonSchemaTypeMatchesValue = (schema: JSONSchemaProperty, value: unknown): boolean => {
+ const schemaType = schema.type;
+
+ if (Array.isArray(schemaType)) {
+ return schemaType.some(type => jsonSchemaTypeMatchesValue({ ...schema, type }, value));
+ }
+
+ if (schemaType === undefined) {
+ if (schema.properties) return isPlainObject(value);
+ if (schema.items) return Array.isArray(value);
+ return false;
+ }
+
+ switch (schemaType) {
+ case 'array':
+ return Array.isArray(value);
+ case 'object':
+ return isPlainObject(value);
+ case 'string':
+ return typeof value === 'string';
+ case 'integer':
+ return Number.isInteger(value);
+ case 'number':
+ return typeof value === 'number';
+ case 'boolean':
+ return typeof value === 'boolean';
+ case 'null':
+ return value === null;
+ default:
+ return false;
+ }
+};
+
+/**
+ * Picks the file-bearing `anyOf`/`oneOf`/`allOf` variant whose JSON Schema
+ * shape matches the runtime value, falling back to the first file-bearing
+ * variant to preserve historical behavior.
+ */
+export const findSchemaVariantWithFileProperty = (
+ schema: JSONSchemaProperty | undefined,
+ property: 'file_uploadable' | 'file_downloadable',
+ value: unknown
+): JSONSchemaProperty | undefined => {
+ const candidates = getSchemaVariants(schema).filter(variant =>
+ schemaHasFileProperty(variant, property)
+ );
+
+ return (
+ candidates.find(candidate => jsonSchemaTypeMatchesValue(candidate, value)) ?? candidates[0]
+ );
+};
+
+/**
+ * Recursively walks a runtime value alongside its (already dereferenced)
+ * JSON-Schema node and passes every value sitting at a `file_uploadable`
+ * node through `leaf`. A leaf returning {@link DELETE_VALUE} is omitted from
+ * its parent object/array. Returns a **new** value; nothing is mutated.
+ *
+ * Composed schemas are resolved to the single file-bearing variant whose
+ * shape matches the value: with `oneOf`, exactly one variant should apply at
+ * runtime, and applying several would stage the same file once per variant.
+ */
+export const walkFileUploadableLeaves = async (
+ value: unknown,
+ schema: JSONSchemaProperty | undefined,
+ leaf: (value: unknown) => Promise<unknown>
+): Promise<unknown> => {
+ if (schema?.file_uploadable) {
+ return leaf(value);
+ }
+
+ const uploadableVariant = findSchemaVariantWithFileProperty(schema, 'file_uploadable', value);
+ if (uploadableVariant) {
+ return walkFileUploadableLeaves(value, uploadableVariant, leaf);
+ }
+
+ if (schema?.type === 'object' && schema.properties && isPlainObject(value)) {
+ const transformed: Record<string, unknown> = {};
+ for (const [k, v] of Object.entries(value)) {
+ const walked = await walkFileUploadableLeaves(v, schema.properties[k], leaf);
+ if (walked !== DELETE_VALUE) transformed[k] = walked;
+ }
+ return transformed;
+ }
+
+ if (schema?.type === 'array' && schema.items && Array.isArray(value)) {
+ // `items` can be a single schema or an array of schemas; we handle both.
+ const itemSchema = Array.isArray(schema.items) ? schema.items[0] : schema.items;
+ const walked = await Promise.all(
+ value.map(item => walkFileUploadableLeaves(item, itemSchema as JSONSchemaProperty, leaf))
+ );
+ return walked.filter(item => item !== DELETE_VALUE);
+ }
+
+ return value;
+};
+
+/**
+ * Omits `''` at `file_uploadable` leaves of `args` without uploading
+ * anything. This is the schema-aware half of the upload modifier that needs
+ * no filesystem access, so it also runs when automatic upload is disabled:
+ * an empty file value is never a valid staged descriptor and the backend
+ * would reject it (https://github.com/ComposioHQ/composio/issues/4233).
+ * Any other value — a local path, a staged descriptor, a list — is
+ * forwarded untouched.
+ */
+export const dropEmptyFileUploads = (
+ args: Record<string, unknown>,
+ schema: JSONSchemaProperty | undefined
+): Promise<unknown> =>
+ walkFileUploadableLeaves(args, schema, async value =>
+ isEmptyFileValue(value) ? DELETE_VALUE : value
+ );
diff --git a/ts/packages/core/test/tools/fileModifiers.test.ts b/ts/packages/core/test/tools/fileModifiers.test.ts
index fb3e557bf..37924b723 100644
--- a/ts/packages/core/test/tools/fileModifiers.test.ts
+++ b/ts/packages/core/test/tools/fileModifiers.test.ts
@@ -311,6 +311,55 @@ describe('FileToolModifier', () => {
availableVersions: ['20251201_01'],
};
+ it('drops empty file values instead of uploading them (issue #4233)', async () => {
+ const fileUploadable = {
+ type: 'object' as const,
+ title: 'FileUploadable',
+ file_uploadable: true,
+ properties: {
+ name: { type: 'string' as const },
+ mimetype: { type: 'string' as const },
+ s3key: { type: 'string' as const },
+ },
+ required: ['name', 'mimetype', 's3key'],
+ };
+ const gmailLikeTool: Tool = {
+ ...mockTool,
+ inputParameters: {
+ type: 'object',
+ properties: {
+ subject: { type: 'string' },
+ attachment: { anyOf: [fileUploadable, { type: 'array', items: fileUploadable }] },
+ extra: { type: 'array', items: fileUploadable },
+ thread_id: { type: 'string' },
+ },
+ },
+ };
+ const staged = { name: 'a.txt', mimetype: 'text/plain', s3key: 'k' };
+
+ const result = await fileToolModifier.fileUploadModifier(gmailLikeTool, {
+ toolSlug: 'test-tool',
+ toolkitSlug: 'test-toolkit',
+ params: {
+ arguments: {
+ subject: 'Test',
+ attachment: '',
+ extra: ['', staged],
+ thread_id: '',
+ },
+ userId: 'test-user',
+ },
+ });
+
+ expect(fileUtils.getFileDataAfterUploadingToS3).not.toHaveBeenCalled();
+ expect(result.arguments).toEqual({
+ subject: 'Test',
+ extra: [staged],
+ // non-file empty strings are not the walker's business
+ thread_id: '',
+ });
+ });
+
it('should upload file for file_uploadable parameters', async () => {
const mockFileData = {
name: 'file.txt',
@@ -2035,6 +2084,48 @@ describe('Tools with dangerouslyAllowAutoUploadDownloadFiles', () => {
);
});
+ it('omits empty file values from the request when auto-upload is off (issue #4233)', async () => {
+ vi.spyOn(context.tools, 'getRawComposioToolBySlug').mockResolvedValue(mockToolWithFileUpload);
+
+ await context.tools.execute('COMPOSIO_TOOL', {
+ arguments: { file: '', text: 'keep' },
+ userId: 'test-user',
+ dangerouslySkipVersionCheck: true,
+ });
+
+ expect(fileUtils.getFileDataAfterUploadingToS3).not.toHaveBeenCalled();
+ expect(mockClient.tools.execute.mock.calls[0]?.[1]?.arguments).toEqual({ text: 'keep' });
+ });
+
+ it('omits empty file values reachable only through a $ref (issue #4233)', async () => {
+ // Composio toolkits express file flags through `$ref`/`$defs`, so the
+ // cheap "does this tool take a file?" gate has to see through the
+ // indirection or the fix never fires for a real tool.
+ vi.spyOn(context.tools, 'getRawComposioToolBySlug').mockResolvedValue({
+ ...mockToolWithFileUpload,
+ inputParameters: {
+ type: 'object',
+ properties: { file: { $ref: '#/$defs/Attachment' }, text: { type: 'string' } },
+ $defs: {
+ Attachment: {
+ type: 'object',
+ file_uploadable: true,
+ properties: { name: { type: 'string' }, s3key: { type: 'string' } },
+ },
+ },
+ },
+ });
+
+ await context.tools.execute('COMPOSIO_TOOL', {
+ arguments: { file: '', text: 'keep' },
+ userId: 'test-user',
+ dangerouslySkipVersionCheck: true,
+ });
+
+ expect(fileUtils.getFileDataAfterUploadingToS3).not.toHaveBeenCalled();
+ expect(mockClient.tools.execute.mock.calls[0]?.[1]?.arguments).toEqual({ text: 'keep' });
+ });
+
it('warns once per tool when auto-upload is off and the tool has a file-uploadable input', async () => {
const warnSpy = vi.spyOn((await import('../../src/utils/logger')).default, 'warn');
warnSpy.mockImplementation(() => {}); // silence the log in test output