feat(harness): support sandbox-side artifact delivery without host byte buffering

[q827505931]

Problem

ArtifactDeliveryTool.deliverArtifact unconditionally calls filesystem.downloadFiles(...) before invoking ArtifactDeliveryTarget. ArtifactDeliveryRequest carries a byte[], so the entire artifact must pass through the host JVM even when the sandbox could upload it directly to object storage or WebDAV.

For large reports, archives, and videos this adds host heap pressure and a sandbox-to-host transfer. A target cannot opt out because it is called only after the download. This follows up on the delivery tool introduced for #2663.

Proposed change

Add an opt-in path-based delivery SPI that receives the active filesystem, per-call runtime context, and normalized source/destination metadata before any download. Applications can then implement sandbox-side uploads through their backend SDK or shell, without host byte materialization.

Keep existing byte-based target implementations and builder configuration compatible. Preserve input validation, destination conflict handling, and force. A direct-upload failure should be returned, not silently retried through a full in-memory download.

Acceptance criteria

• Direct delivery never invokes downloadFiles, including failure/conflict paths.
• Normalized source path, active filesystem, runtime context, destination name, description, and force reach the target.
• Existing byte-based targets retain their behavior.
• Document application responsibility for backend path resolution, upload execution, source checks, and destination conflicts.

[oss-maintainer]

Issue Evaluation

Category: enhancement | Status: Evaluated — valid proposal, already covered by open PR #3031

Checked against main (7399ed61): the report describes the current behaviour accurately.

• agentscope-harness/src/main/java/io/agentscope/harness/agent/tool/ArtifactDeliveryTool.java:126 — delivery unconditionally calls filesystem.downloadFiles(runtimeContext, List.of(normalized)).
• agentscope-harness/src/main/java/io/agentscope/harness/agent/artifact/ArtifactDeliveryRequest.java:38 — the record carries byte[] content, so a target has no way to receive a path and skip host materialisation; the SPI is only invoked after the download.

No automated proposal will be generated here — the issue author already shipped it in #3031 (feat(harness): allow direct artifact delivery without host buffering, opened the same day, non-draft, MERGEABLE, currently APPROVED), which adds a DirectArtifactDeliveryTarget / ArtifactDeliverySource seam, branches on it in ArtifactDeliveryTool before the downloadFiles call, covers both the success and failure/conflict paths in ArtifactDeliveryToolTest, and updates docs/v2/{en,zh}/docs/harness/sandbox.md. That is the same design as proposed here, so filing a competing change would only add noise.

What this issue still needs from the project side is a maintainer merge decision on #3031 (all review prerequisites from our side are already satisfied by that PR's own tests + docs). One point worth carrying into that merge, not as a new scope request but as a contract note: the "a direct-upload failure is returned, never silently retried through the full in-memory download" rule is an API promise that is easy to regress later, because both paths now live in the same method — the existing test that asserts downloadFiles is never invoked for a direct target is the guard that must not be weakened.

---

Automated evaluation by github-manager-bot