fix(deepagents): add default chunked upload/download to BaseSandbox

[Dr. Tristan Behrens (AI-Guru)]

Summary

• Add concrete upload_files() and download_files() implementations to BaseSandbox, replacing the current @abstractmethod stubs
• Small files (<64KB) use a single execute() call (same as before)
• Large files are split into 64KB base64 chunks to avoid hitting the Linux kernel ARG_MAX limit (~128KB per argument)
• Downloads also chunk to avoid execute() output truncation
• Methods are non-abstract so backends with native file transfer (SSH/SFTP, Daytona REST) can still override them

Problem

When using sandbox backends that route file transfers through execute() (Docker with tmpfs, microsandbox), uploading binary files larger than ~100KB fails with:

exec /bin/bash: argument list too long

This happens because the base64-encoded file content is embedded in the command string passed to exec_run(), which exceeds the kernel's ARG_MAX limit. Docker's put_archive API cannot be used as a workaround because tmpfs mounts are invisible to it.

The error is particularly problematic for autonomous workflows that generate binary artifacts (PDFs, images) inside sandboxed containers.

Solution

BaseSandbox already provides default implementations of read(), write(), edit(), ls_info(), glob_info(), and grep_raw() via execute(). This PR extends that pattern to upload_files() and download_files():

• Upload: Files over 64KB are base64-encoded, split into chunks, each chunk appended to a temp file inside the sandbox via separate execute() calls, then the assembled base64 is decoded to the final path
• Download: Files over 64KB are read in binary chunks inside the sandbox, each chunk base64-encoded and returned via separate execute() calls, then reassembled on the host

All operations go through execute(), respecting the full middleware chain.

Test plan

• Unit tests: 6 new tests covering small file upload, large file chunking, upload error handling, small file download, large file chunked download, and missing file error
• All 15 sandbox backend tests pass
• Verified end-to-end with Docker backend: 301KB PDF upload/download roundtrip succeeds
• Verified 1MB random binary roundtrip with byte-level fidelity

🤖 Generated with Claude Code

[Eugene Yurtsev (eyurtsev)]

If you're interested in working on this feature, could you try to match the style of the other provided implementations (e.,g., write_file etc)?

offload as much as you can into the template which attempts to make it easier to see the boundary between python and shell code (makes it easier to verify that the implementation does not security issues)

Make sure that everything that needs to be escaped is escaped properly so there's no additional attack surface

[Dr. Tristan Behrens (AI-Guru)]

Done! Refactored all upload/download methods to use module-level _COMMAND_TEMPLATE constants matching the existing _WRITE_COMMAND_TEMPLATE / _EDIT_COMMAND_TEMPLATE pattern.

Seven new templates added: _UPLOAD_COMMAND_TEMPLATE, _UPLOAD_CHUNK_COMMAND_TEMPLATE, _UPLOAD_DECODE_COMMAND_TEMPLATE, _REMOVE_COMMAND_TEMPLATE, _DOWNLOAD_SIZE_COMMAND_TEMPLATE, _DOWNLOAD_COMMAND_TEMPLATE, _DOWNLOAD_CHUNK_COMMAND_TEMPLATE.

All file paths are now base64-encoded before interpolation (safe charset [A-Za-z0-9+/=]), which also eliminates the shell injection risk from the previous string concatenation approach. Template format tests added for each.

[Eugene Yurtsev (eyurtsev)]

is ARG_MAX relevant if we're feeding through stdin?

[Dr. Tristan Behrens (AI-Guru)]

Good question! ARG_MAX itself (typically ~2MB) is the total size limit for all arguments + environment passed to execve(). But the more relevant constraint here is MAX_ARG_STRLEN (typically PAGE_SIZE * 32 = 128KB on Linux), which limits any single argument string.

When we use bash -c 'script<<heredoc', the entire string — including the heredoc content — is passed as a single argument to execve(). So heredocs via bash -c don't bypass the limit the way a standalone heredoc in an interactive shell would (where bash itself reads from stdin).

With 64KB raw chunks → ~87KB base64, we stay safely under the 128KB MAX_ARG_STRLEN per-argument limit.

I've updated the comments in the code to reference MAX_ARG_STRLEN instead of ARG_MAX to be more precise about which kernel limit actually applies.