Add file upload/download helpers

[dhirajsb]

Motivation

Today, users may need to shell out through execution calls to move files into or out of an OpenShell environment. First-class file helpers would make common workflows safer and more ergonomic.

Proposed change

Add Python SDK helpers such as:

client.upload_file(local_path, remote_path)
client.download_file(remote_path, local_path)

The first step should confirm whether the existing gateway/proto supports efficient and safe file transfer. If it does not, this issue can become the design anchor for adding the required protocol support.

Acceptance criteria

• Determine whether this can be implemented SDK-only or requires gateway/proto changes.
• Document the chosen design and security constraints.
• Add upload/download helpers if supported.
• Include tests for path validation, missing files, overwrite behavior, and error propagation.

Notes

This may require server-side coordination depending on the current protocol surface.

[johntmyers]

@dhirajsb have you looked at #1590 - this is a lot of one-off issues for an SDK experience that we already know needs a holistic design and requirements around. If we need to cover all of these then it might be better to aggregate them into as single issue at least.

[zanetworker]

@johntmyers this is also related: #1707

[matthewgrossman]

📋 triage-agent

Triage Assessment

Classification: duplicate

Summary

#1707 already tracks typed, streaming upload/download RPCs and SDK helpers, including binary safety, large files, permissions, and error handling.

Investigation

This issue requests the same SDK file-transfer surface but leaves the gateway/protocol design open; #1707 is the more complete canonical design.

Recommendation

Closing as a duplicate of #1707. Please continue file-transfer design and implementation there.