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): preserve downloads when destination names collide
jkomyno committed
Sep 30, 2026 at 12:20 UTC
9a23381d75051e0f791f4e91574cc01f269ba922
13 files changed
+227
-19
.changeset/remote-file-portable-names.md
+1
-1
@@ -2,4 +2,4 @@
2
'@composio/core': patch
3
---
4
5
-`RemoteFile.save()` without a path no longer rejects ordinary file names. Names with characters Windows reserves, such as `report_2026-09-29T10:30:00.csv` or `What is this?.png`, are saved with those characters replaced by `_`. Names longer than 128 bytes are truncated with their extension kept, and reserved device names such as `NUL` get a `_` prefix. A name changed this way also gets a short digest of the original before its extension (`What is this_-9c68adf2da8b6e8d.png`), so two files whose names differ only in those characters never overwrite each other. Names with a NUL byte or no usable basename are still refused.
5
+`RemoteFile.save()` without a path no longer rejects ordinary file names. Names with characters Windows reserves, such as `report_2026-09-29T10:30:00.csv` or `What is this?.png`, are saved with those characters replaced by `_`. Names longer than 128 bytes are truncated with their extension kept, and reserved device names such as `NUL` get a `_` prefix. A name changed this way also gets a short digest of the original before its extension (`What is this_-9c68adf2da8b6e8d.png`). Default saves create a new file exclusively; if the destination exists, a copy number is added before its extension. Repeated default saves therefore return distinct paths and preserve earlier downloads. Names with a NUL byte or no usable basename are still refused.
python/composio/core/models/_files.py
+11
-4
@@ -27,7 +27,7 @@ from composio.exceptions import (
27
)
28
from composio.utils import mimetypes
29
from composio.utils.json_schema import dereference_json_schema
30
-from composio.utils.safe_path import secure_basename_join, secure_join
30
+from composio.utils.safe_path import open_unique_file, secure_basename_join, secure_join
31
from composio.utils.url_safety import (
32
parse_content_length,
33
safe_get,
@@ -748,12 +748,17 @@ class FileDownloadable(BaseModel):
748
)
749
750
total_bytes = 0
751
+ created = False
752
try:
753
# Only once the fetch is validated and connected, so a blocked URL
754
# leaves no directory behind — and inside the `try`, so a failure
755
# here still closes the response.
756
outdir.mkdir(exist_ok=True, parents=True)
756
- with outfile.open("wb") as fd:
757
+ # A literal server name can equal a digest-tagged name. Claim the
758
+ # path exclusively, then choose a numbered name if it exists.
759
+ outfile, fd = open_unique_file(outfile)
760
+ created = True
761
+ with fd:
762
for chunk in response.iter_content(chunk_size=chunk_size):
763
if chunk:
764
total_bytes += len(chunk)
@@ -766,14 +771,16 @@ class FileDownloadable(BaseModel):
771
except ResponseTooLargeError:
772
# Propagates uncaught — callers must see the limit hit — but the
773
# truncated file must not be left behind as if it were the download.
769
- _discard_partial_download(outfile)
774
+ if created:
775
+ _discard_partial_download(outfile)
776
raise
777
except OSError as e:
778
# `requests.exceptions.RequestException` subclasses `OSError`, so a
779
# mid-stream transport failure and a failing `fd.write`/`mkdir`
780
# (disk full, permissions) both land here — and both owe the caller
781
# the `ErrorDownloadingFile` this method documents.
776
- _discard_partial_download(outfile)
782
+ if created:
783
+ _discard_partial_download(outfile)
784
raise ErrorDownloadingFile(
785
"Error downloading file: "
786
f"{_sanitize_url_for_logging(self.s3url)}. Error: {type(e).__name__}"
python/composio/core/models/tool_router_session_files.py
+8
-2
@@ -28,7 +28,7 @@ from composio.exceptions import (
28
ValidationError,
29
)
30
from composio.utils.mimetypes import get_extension_from_mime_type
31
-from composio.utils.safe_path import secure_basename_join
31
+from composio.utils.safe_path import open_unique_file, secure_basename_join
32
from composio.utils.url_safety import (
33
parse_content_length,
34
safe_get,
@@ -232,6 +232,7 @@ class RemoteFile:
232
233
Returns the absolute path where the file was saved.
234
If path is omitted, saves to ~/.composio/files/ using the filename.
235
+ An existing default destination gets a copy number before its extension.
236
"""
237
content = self.buffer()
238
save_path: Path
@@ -256,7 +257,12 @@ class RemoteFile:
257
raise ValidationError(str(e)) from e
258
259
save_path.parent.mkdir(parents=True, exist_ok=True)
259
- save_path.write_bytes(content)
260
+ if path is not None:
261
+ save_path.write_bytes(content)
262
+ else:
263
+ save_path, fd = open_unique_file(save_path)
264
+ with fd:
265
+ fd.write(content)
266
return str(save_path.resolve())
267
268
@classmethod
python/composio/utils/safe_path.py
+35
-2
@@ -185,6 +185,37 @@ def _fit_filename_bytes(name: str, max_bytes: int = MAX_COMPONENT_LENGTH) -> str
185
return _truncate_to_bytes(stem, max_bytes - _encoded_length(extension)) + extension
186
187
188
+def numbered_basename(name: str, copy: int) -> str:
189
+ """Add a copy number before the extension within the filename byte limit."""
190
+ suffix = f"-{copy}"
191
+ stem, extension = _split_extension(name)
192
+ return (
193
+ _truncate_to_bytes(
194
+ stem, MAX_COMPONENT_LENGTH - _encoded_length(extension) - len(suffix)
195
+ )
196
+ + suffix
197
+ + extension
198
+ )
199
+
200
+
201
+def open_unique_file(path: Path) -> t.Tuple[Path, t.BinaryIO]:
202
+ """Claim a validated download path without replacing an existing file.
203
+
204
+ Numbered alternatives stay in the same directory and preserve a short
205
+ extension. Exclusive creation also prevents concurrent saves from sharing
206
+ a destination.
207
+ """
208
+ copy = 0
209
+ while True:
210
+ candidate = (
211
+ path if copy == 0 else path.with_name(numbered_basename(path.name, copy))
212
+ )
213
+ try:
214
+ return candidate, candidate.open("xb")
215
+ except FileExistsError:
216
+ copy += 1
217
+
218
+
219
_FNV_OFFSET_BASIS_64 = 0xCBF29CE484222325
220
_FNV_PRIME_64 = 0x100000001B3
221
_UINT64_MASK = 0xFFFFFFFFFFFFFFFF
@@ -238,8 +269,10 @@ def safe_basename(name: str, *, label: str = "filename") -> str:
269
extension kept, trailing spaces and dots are dropped as Windows would, and
270
a resulting reserved device name gets a ``_`` prefix. A name any of these
271
rules changed is then tagged with a digest of the original before its
241
- extension (``report_-<16 hex>.png``), so distinct names never land on the
242
- same file; a name that was already portable is returned unchanged.
272
+ extension (``report_-<16 hex>.png``) to distinguish ordinary normalization
273
+ collisions; a name that was already portable is returned unchanged. The
274
+ result can still equal a literal server name, so download writes use
275
+ :func:`open_unique_file` to preserve existing files.
276
``safeBasename`` in the TypeScript SDK applies the same rules in the same
277
order.
278
python/tests/test_files.py
+42
-2
@@ -2686,8 +2686,11 @@ class TestDownloadSizeLimit:
2686
with pytest.raises(ResponseTooLargeError):
2687
self._downloadable().download(outdir=tmp_path, root=tmp_path, max_size=1024)
2688
2689
+ @pytest.mark.parametrize("existing", [False, True])
2690
@patch("composio.core.models._files.safe_request")
2690
- def test_download_removes_partial_file_on_failure(self, mock_get, tmp_path):
2691
+ def test_download_removes_partial_file_on_failure(
2692
+ self, mock_get, tmp_path, existing
2693
+ ):
2694
"""A truncated download must not be left behind as if it succeeded."""
2695
mock_response = MagicMock()
2696
mock_response.status_code = 200
@@ -2696,10 +2699,17 @@ class TestDownloadSizeLimit:
2699
mock_response.close = MagicMock()
2700
mock_get.return_value = mock_response
2701
2702
+ if existing:
2703
+ (tmp_path / "report.bin").write_bytes(b"original")
2704
+
2705
with pytest.raises(ResponseTooLargeError):
2706
self._downloadable().download(outdir=tmp_path, root=tmp_path, max_size=1024)
2707
2702
- assert list(tmp_path.iterdir()) == []
2708
+ if existing:
2709
+ assert list(tmp_path.iterdir()) == [tmp_path / "report.bin"]
2710
+ assert (tmp_path / "report.bin").read_bytes() == b"original"
2711
+ else:
2712
+ assert list(tmp_path.iterdir()) == []
2713
2714
@patch("composio.core.models._files.safe_request")
2715
def test_download_accepts_file_within_limit(self, mock_get, tmp_path):
@@ -3215,6 +3225,36 @@ class TestFileDownloadablePathTraversal:
3225
b"\x02",
3226
]
3227
3228
+ @pytest.mark.parametrize(
3229
+ "names",
3230
+ [
3231
+ ["report?.png", "report_-05fcb95aa5b918e9.png"],
3232
+ ["report_-05fcb95aa5b918e9.png", "report?.png"],
3233
+ ["請" * 41 + ".pdf"] * 3,
3234
+ ],
3235
+ )
3236
+ def test_literal_tag_name_does_not_overwrite_download(self, names, tmp_path):
3237
+ outdir = tmp_path / "safe"
3238
+ outfiles = []
3239
+ for index, name in enumerate(names):
3240
+ file = FileDownloadable(
3241
+ name=name,
3242
+ mimetype="image/png",
3243
+ s3url="https://example.com/file",
3244
+ )
3245
+ with patch(
3246
+ "composio.core.models._files.safe_request",
3247
+ return_value=self._mock_response(bytes([index])),
3248
+ ):
3249
+ outfiles.append(file.download(outdir, root=outdir))
3250
+
3251
+ assert len(set(outfiles)) == len(names)
3252
+ assert [outfile.read_bytes() for outfile in outfiles] == [
3253
+ bytes([i]) for i in range(len(names))
3254
+ ]
3255
+ assert all(len(outfile.name.encode()) <= 128 for outfile in outfiles)
3256
+ assert all(outfile.suffix == Path(names[0]).suffix for outfile in outfiles)
3257
+
3258
3259
class TestDownloadDirSlugTraversal:
3260
"""Server-controlled tool/toolkit slugs must not relocate the download
python/tests/test_path_join_guardrail.py
+2
-1
@@ -128,7 +128,8 @@ REVIEWED_JOINS: t.Dict[t.Tuple[str, str], t.Dict[str, t.Any]] = {
128
"`safe_basename` collapses the value, rejects NUL bytes and invalid "
129
"Unicode, rewrites Windows-invalid forms and reserved device names, fits "
130
"the encoded length, and tags a rewritten name with a digest of the "
131
- "original so distinct names never share a file.",
131
+ "original to distinguish ordinary normalization collisions. Download "
132
+ "writes create files exclusively to preserve existing destinations.",
133
"_encoded_length",
134
"_fit_filename_bytes",
135
"_tag_with_original",
python/tests/test_tool_router_session_files.py
+28
@@ -378,6 +378,34 @@ class TestRemoteFile:
378
assert saved.name == expected
379
assert saved.read_bytes() == b"content"
380
381
+ @pytest.mark.parametrize(
382
+ "names",
383
+ [
384
+ ["report?.png", "report_-05fcb95aa5b918e9.png"],
385
+ ["report_-05fcb95aa5b918e9.png", "report?.png"],
386
+ ["請" * 41 + ".pdf"] * 3,
387
+ ],
388
+ )
389
+ def test_default_save_preserves_files_with_colliding_names(self, names, tmp_path):
390
+ paths = []
391
+ with patch("pathlib.Path.home", return_value=tmp_path):
392
+ for index, name in enumerate(names):
393
+ file = RemoteFile(
394
+ expires_at="2026-01-01",
395
+ mount_relative_path=name,
396
+ sandbox_mount_prefix="/mnt/files",
397
+ download_url="https://example.com/file",
398
+ )
399
+ with patch.object(file, "buffer", return_value=bytes([index])):
400
+ paths.append(Path(file.save()))
401
+
402
+ assert len(set(paths)) == len(names)
403
+ assert [path.read_bytes() for path in paths] == [
404
+ bytes([i]) for i in range(len(names))
405
+ ]
406
+ assert all(len(path.name.encode()) <= 128 for path in paths)
407
+ assert all(path.suffix == Path(names[0]).suffix for path in paths)
408
+
409
410
class TestResponseDerivedUrlsAreGuarded:
411
"""`download_url` and `upload_url` are response fields, so they are guarded.
ts/packages/core/src/models/RemoteFile.ts
+24
-5
@@ -1,6 +1,9 @@
1
import { platform } from '#platform';
2
import { ssrfSafeFetchWhereSupported } from '#ssrf_guard';
3
import { COMPOSIO_DIR, TEMP_FILES_DIRECTORY_NAME } from '../utils/constants';
4
+import { z } from 'zod';
5
+
6
+const existingFileError = z.object({ code: z.literal('EEXIST') });
7
8
function getParentDir(filePath: string): string {
9
const lastSep = Math.max(filePath.lastIndexOf('/'), filePath.lastIndexOf('\\'));
@@ -14,7 +17,7 @@ import {
17
ValidationError,
18
} from '../errors';
19
import { readResponseBodyWithLimit } from '../utils/readResponseBody';
17
-import { safeBasename, untrustedBasename } from '../utils/safePath';
20
+import { numberedBasename, safeBasename, untrustedBasename } from '../utils/safePath';
21
22
/**
23
* Represents a file stored in a tool router session's file mount.
@@ -173,6 +176,7 @@ export class RemoteFile {
176
* Requires a Node.js runtime with file system support (not available in Cloudflare Workers/Edge).
177
*
178
* @param path - Local path to save the file. If omitted, saves to the Composio temp directory using the filename from the mount path.
179
+ * An existing default destination gets a copy number before its extension.
180
* @returns The absolute path where the file was saved
181
* @throws Error if file system is not supported or the save fails
182
* @throws ValidationError if `path` is omitted and the mount path yields no usable filename
@@ -196,8 +200,8 @@ export class RemoteFile {
200
// `"."` or `"foo/.."` would otherwise make `savePath` its own directory or
201
// the parent, and fail with a raw `EISDIR` only after `mkdirSync` had run.
202
const defaultDir = platform.joinPath(homeDir, COMPOSIO_DIR, TEMP_FILES_DIRECTORY_NAME);
199
- const savePath =
200
- path ?? platform.joinPath(defaultDir, safeBasename(this.mountRelativePath, 'mount path'));
203
+ const defaultName = path == null ? safeBasename(this.mountRelativePath, 'mount path') : '';
204
+ const savePath = path ?? platform.joinPath(defaultDir, defaultName);
205
206
const content = await this.buffer();
207
@@ -206,7 +210,22 @@ export class RemoteFile {
210
platform.mkdirSync(dir);
211
}
212
209
- platform.writeFileSync(savePath, content);
210
- return savePath;
213
+ if (path != null) {
214
+ platform.writeFileSync(savePath, content);
215
+ return savePath;
216
+ }
217
+
218
+ // Server names can equal a digest-tagged name literally. Reserve a new
219
+ // destination atomically so either save order keeps both downloads.
220
+ for (let copy = 0; ; copy++) {
221
+ const destination =
222
+ copy === 0 ? savePath : platform.joinPath(defaultDir, numberedBasename(defaultName, copy));
223
+ try {
224
+ platform.writeFileExclusiveSync(destination, content);
225
+ return destination;
226
+ } catch (error) {
227
+ if (!existingFileError.safeParse(error).success) throw error;
228
+ }
229
+ }
230
}
231
}
ts/packages/core/src/platform/node.ts
+4
@@ -108,4 +108,8 @@ export const platform = {
108
fs.writeFileSync(filePath, content);
109
}
110
},
111
+
112
+ writeFileExclusiveSync(filePath: string, content: Uint8Array): void {
113
+ fs.writeFileSync(filePath, content, { flag: 'wx' });
114
+ },
115
} as Platform;
ts/packages/core/src/platform/types.ts
+3
@@ -85,6 +85,9 @@ export interface Platform {
85
writeFileSync(filePath: string, content: Uint8Array, encoding?: never): void;
86
writeFileSync(filePath: string, content: string, encoding: Uint8ArrayEncoding): void;
87
88
+ /** Writes a new file, failing if its path already exists. */
89
+ writeFileExclusiveSync(filePath: string, content: Uint8Array): void;
90
+
91
/**
92
* Indicates whether this platform supports file system operations.
93
* Edge runtimes like Cloudflare Workers return false.
ts/packages/core/src/platform/workerd.ts
+4
@@ -108,4 +108,8 @@ export const platform: Platform = {
108
'Use environment variables or external storage services instead.'
109
);
110
},
111
+
112
+ writeFileExclusiveSync(_filePath: string, _content: Uint8Array): never {
113
+ throw new Error('File system operations are not supported in this runtime environment.');
114
+ },
115
};
ts/packages/core/src/utils/safePath.ts
+15
-2
@@ -156,6 +156,17 @@ function fitFilenameBytes(name: string, maxBytes: number = MAX_FILENAME_BYTES):
156
return truncateToBytes(stem, maxBytes - utf8Length(extension)) + extension;
157
}
158
159
+/** Adds a copy number before the extension without exceeding the filename byte limit. */
160
+export function numberedBasename(name: string, copy: number): string {
161
+ const suffix = `-${copy}`;
162
+ const [stem, extension] = splitExtension(name);
163
+ return (
164
+ truncateToBytes(stem, MAX_FILENAME_BYTES - utf8Length(extension) - suffix.length) +
165
+ suffix +
166
+ extension
167
+ );
168
+}
169
+
170
/**
171
* Tags a name that portability changed with a digest of the name it came
172
* from, before the extension: `report?.png` and `report*.png` both become
@@ -189,8 +200,10 @@ function tagWithOriginal(portable: string, original: string): string {
200
* spaces and dots are dropped as Windows would, and a resulting reserved
201
* device name gets a `_` prefix. A name any of these rules changed is then
202
* tagged with a digest of the original before its extension
192
- * (`report_-<16 hex>.png`), so distinct names never land on the same file; a
193
- * name that was already portable is returned unchanged. `safe_basename` in
203
+ * (`report_-<16 hex>.png`) to distinguish ordinary normalization collisions;
204
+ * a name that was already portable is returned unchanged. A result can still
205
+ * equal a literal server name, so default saves create files exclusively.
206
+ * `safe_basename` in
207
* the Python SDK applies the same rules in the same order.
208
*
209
* Python-compatible stripping removes surrounding whitespace first, and the
ts/packages/core/test/models/RemoteFile.test.ts
+50
@@ -361,6 +361,56 @@ describe('RemoteFile', () => {
361
).toEqual(bodies);
362
});
363
364
+ it.each([
365
+ ['report?.png', 'report_-05fcb95aa5b918e9.png'],
366
+ ['report_-05fcb95aa5b918e9.png', 'report?.png'],
367
+ ])('should keep both downloads when %j and %j map to one name', async (first, second) => {
368
+ const { platform } = await import('../../src/platform/node');
369
+ const bodies = [new Uint8Array([1]), new Uint8Array([2])];
370
+ globalThis.fetch = vi
371
+ .fn()
372
+ .mockResolvedValueOnce({ ok: true, arrayBuffer: () => Promise.resolve(bodies[0].buffer) })
373
+ .mockResolvedValueOnce({
374
+ ok: true,
375
+ arrayBuffer: () => Promise.resolve(bodies[1].buffer),
376
+ });
377
+
378
+ const paths = [];
379
+ for (const mountRelativePath of [first, second]) {
380
+ paths.push(await new RemoteFile({ ...validCamelCaseData, mountRelativePath }).save());
381
+ }
382
+
383
+ expect(new Set(paths).size).toBe(2);
384
+ expect(paths.map(path => new Uint8Array(platform.readFileSync(path)))).toEqual(bodies);
385
+ });
386
+
387
+ it('should preserve concurrent default saves within the filename byte limit', async () => {
388
+ const { platform } = await import('../../src/platform/node');
389
+ const bodies = [new Uint8Array([1]), new Uint8Array([2]), new Uint8Array([3])];
390
+ let nextBody = 0;
391
+ globalThis.fetch = vi.fn().mockImplementation(() => {
392
+ const body = bodies[nextBody++];
393
+ return Promise.resolve({ ok: true, arrayBuffer: () => Promise.resolve(body.buffer) });
394
+ });
395
+ const files = bodies.map(
396
+ () =>
397
+ new RemoteFile({
398
+ ...validCamelCaseData,
399
+ mountRelativePath: `${'請'.repeat(41)}.pdf`,
400
+ })
401
+ );
402
+
403
+ const paths = await Promise.all(files.map(file => file.save()));
404
+
405
+ expect(new Set(paths).size).toBe(3);
406
+ expect(paths.map(path => new Uint8Array(platform.readFileSync(path)))).toEqual(bodies);
407
+ for (const path of paths) {
408
+ const name = path.slice(path.lastIndexOf('/') + 1);
409
+ expect(new TextEncoder().encode(name).length).toBeLessThanOrEqual(128);
410
+ expect(name.endsWith('.pdf')).toBe(true);
411
+ }
412
+ });
413
+
414
// Each of these would make the save path equal its own directory (or the
415
// parent), which previously surfaced as an unhandled `EISDIR` from
416
// `writeFileSync` after the directory had already been created.