fix(sdk): expose download response metadata across all SDKs

[mengdehong]

Summary

• Expose download response metadata across the Go, JavaScript, Python, Kotlin, and C# SDKs.
• The execd API supports HTTP Range downloads, but existing SDK methods only return the response body. Callers therefore cannot distinguish 206 Partial Content from a server or proxy ignoring the Range request and returning 200 OK.
• Add detailed download methods that return:
  • response body;
  • HTTP status code;
  • Content-Type and Content-Disposition;
  • response Content-Length;
  • complete file size;
  • parsed Content-Range;
  • an isPartial convenience property.
• Parse Content-Range values such as bytes 0-1023/4096 into start, end, and total fields. Unknown totals use -1; malformed values preserve the raw header while numeric fields use -1.
• Keep existing download method signatures and return values unchanged. Existing methods delegate to the detailed implementations to avoid duplicating request and error-handling logic.
• Detailed streaming bodies provide explicit close/dispose support so callers can release the HTTP response when a Range request is ignored or a stream is only partially consumed.

New methods:

SDK	Methods
Go	DownloadFileResponse
JavaScript	readBytesDetailed, readBytesStreamDetailed
Python	read_bytes_detailed, read_bytes_stream_detailed (async and sync)
Kotlin	readByteArrayDetailed, readStreamDetailed
C#	ReadBytesDetailedAsync, ReadBytesStreamDetailedAsync

Testing

• Not run (explain why)
• Unit tests
  • Covered 206 Partial Content metadata mapping.
  • Covered Range requests ignored with 200 OK.
  • Covered malformed Content-Range and unknown total size.
  • Covered legacy download method compatibility.
  • Covered unconsumed and partially consumed stream cleanup.
  • Ran all five sandbox SDK test suites.
  • Ran affected CLI and code-interpreter SDK checks.
  • Verified Python 3.10 compatibility and the CI Python 3.11 runtime.
  • Ran formatting, linting, type checking, Go race tests, coverage, license verification, and the documentation build.
• Integration tests
• e2e / manual verification
  • Repository-managed Helm Kind smoke and self-hosted real E2E remain for CI.

Breaking Changes

• None
• Yes
  • Existing SDK download call sites remain compatible because previous method signatures and behavior are unchanged.
  • Custom implementations or mocks of the JavaScript, Python, Kotlin, or C# filesystem interfaces must implement the newly added detailed download methods.
  • Callers using SDK-provided filesystem implementations require no migration.

Checklist

• Linked Issue or clearly described motivation
• Added/updated docs (if needed)
• Added/updated tests (if needed)
• Security impact considered
  • No authentication, authorization, or request behavior changes; the new APIs expose metadata already present on download responses.
• Backward compatibility considered

[Copilot]

Pull request overview

This PR extends the OpenSandbox SDKs’ filesystem download APIs to optionally return HTTP response metadata (status code, Content-* headers, parsed Content-Range, etc.) alongside the downloaded body, enabling callers to reliably detect whether HTTP Range requests were honored (206) or ignored (200). It does so across Go, JavaScript, Python (async + sync), Kotlin, and C#, while preserving existing “body-only” methods by delegating them to the new detailed implementations.

Changes:

• Add new “detailed” download response models (e.g., ReadBytesResponse, ByteRange) and implement detailed download methods in each SDK, keeping existing download methods backward-compatible via delegation.
• Implement consistent Content-Range parsing behavior (including malformed values and unknown totals) and add stream wrappers that support explicit close/dispose for unconsumed/partially-consumed bodies.
• Add/expand unit tests and update SDK docs to describe when to use detailed methods and how to close/dispose detailed stream bodies.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
sdks/sandbox/python/tests/test_filesystem_download_response.py	Adds Python async/sync tests for detailed download metadata + stream cleanup behavior.
sdks/sandbox/python/src/opensandbox/sync/services/filesystem.py	Extends sync filesystem service interface with detailed download method signatures.
sdks/sandbox/python/src/opensandbox/sync/adapters/isolated_filesystem_adapter.py	Implements sync detailed downloads and delegates legacy methods to detailed responses.
sdks/sandbox/python/src/opensandbox/sync/adapters/filesystem_adapter.py	Implements sync detailed downloads and stream bodies with explicit close support.
sdks/sandbox/python/src/opensandbox/services/filesystem.py	Extends async filesystem service interface with detailed download method signatures.
sdks/sandbox/python/src/opensandbox/models/filesystem.py	Introduces Python ByteRange, ReadBytesResponse, and closeable stream Protocols.
sdks/sandbox/python/src/opensandbox/models/init.py	Re-exports the new Python download response models/types from the package root.
sdks/sandbox/python/src/opensandbox/adapters/isolated_filesystem_adapter.py	Implements async detailed downloads and delegates legacy methods to detailed responses.
sdks/sandbox/python/src/opensandbox/adapters/filesystem_adapter.py	Implements async detailed downloads and stream bodies with explicit close support.
sdks/sandbox/python/src/opensandbox/adapters/download_response.py	Adds shared Python mapping/parsing utilities + stream wrappers that close httpx responses.
sdks/sandbox/kotlin/sandbox/src/test/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/FilesystemAdapterTest.kt	Adds Kotlin tests for detailed download metadata and legacy compatibility.
sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/IsolatedFilesystemAdapter.kt	Adds readByteArrayDetailed/readStreamDetailed and delegates legacy methods to detailed.
sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/FilesystemAdapter.kt	Adds readByteArrayDetailed/readStreamDetailed and delegates legacy methods to detailed.
sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/DownloadResponseMapper.kt	Adds Kotlin shared mapper parsing Content-Range + mapping response metadata.
sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/services/Filesystem.kt	Extends Kotlin filesystem interface with detailed read methods.
sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/execd/filesystem/FilesystemModels.kt	Introduces Kotlin ByteRange/ReadBytesResponse models and isPartial convenience property.
sdks/sandbox/javascript/tests/public-exports.test.mjs	Expands JS public export test to cover new stable download response types.
sdks/sandbox/javascript/tests/filesystem.download-response.test.mjs	Adds JS tests for detailed metadata mapping + stream cancel/cleanup behavior.
sdks/sandbox/javascript/src/services/filesystem.ts	Extends JS SandboxFiles interface with detailed download methods.
sdks/sandbox/javascript/src/models/filesystem.ts	Introduces JS ByteRange, ReadBytesResponse, and closeable ReadBytesStream types.
sdks/sandbox/javascript/src/index.ts	Exposes new JS filesystem models/types in the public entrypoint.
sdks/sandbox/javascript/src/adapters/isolatedFilesystemAdapter.ts	Implements readBytesDetailed/readBytesStreamDetailed and delegates legacy downloads.
sdks/sandbox/javascript/src/adapters/filesystemAdapter.ts	Implements readBytesDetailed/readBytesStreamDetailed and delegates legacy downloads.
sdks/sandbox/javascript/src/adapters/downloadResponse.ts	Adds JS response metadata mapper + closeable stream wrapper for Response bodies.
sdks/sandbox/go/sandbox_files.go	Adds Go Sandbox.DownloadFileResponse helper method.
sdks/sandbox/go/README.md	Documents the new Go download method that exposes response metadata.
sdks/sandbox/go/opensandbox_test.go	Adds Go tests for range ignored vs honored, Content-Range parsing, and body close behavior.
sdks/sandbox/go/execd.go	Introduces Go DownloadFileResponse/ByteRange, Content-Range parsing, and delegates legacy DownloadFile.
sdks/sandbox/csharp/tests/OpenSandbox.Tests/SandboxEgressLifecycleTests.cs	Updates C# test filesystem mock to implement newly-added detailed interface methods.
sdks/sandbox/csharp/tests/OpenSandbox.Tests/FilesystemAdapterTests.cs	Adds C# tests validating detailed metadata mapping and stream disposal behavior.
sdks/sandbox/csharp/src/OpenSandbox/Services/ISandboxFiles.cs	Extends C# filesystem interface with detailed download methods for bytes and streams.
sdks/sandbox/csharp/src/OpenSandbox/Models/Filesystem.cs	Introduces C# ByteRange, ReadBytesResponse<T>, and IAsyncReadBytesStream models.
sdks/sandbox/csharp/src/OpenSandbox/Internal/HttpClientWrapper.cs	Makes EnsureSuccessAsync internal to support adapter-level response handling.
sdks/sandbox/csharp/src/OpenSandbox/Adapters/FilesystemAdapter.cs	Implements detailed downloads, metadata mapping, and a disposable async stream wrapper.
docs/sdks/python.md	Documents Python detailed download APIs and explicit close guidance for streams.
docs/sdks/kotlin.md	Documents Kotlin detailed download APIs.
docs/sdks/javascript.md	Documents JS detailed download APIs and explicit close guidance for streams.
docs/sdks/go.md	Documents Go DownloadFileResponse for metadata-aware downloads.
docs/sdks/csharp.md	Documents C# detailed download APIs and explicit dispose guidance for streams.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.