@devries-cameron20 / composio-1 / commits / 9a23381d7
Fork 0

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

fix(sdk): 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.