feat: add OpenSandbox sandbox provider

[dargoner]

AgentScope-Java Version

2.0.3-SNAPSHOT

Description

Add OpenSandbox as a standalone Harness sandbox extension.

• Integrate the official OpenSandbox Java SDK and register the extension in the dependency and distribution BOMs.
• Implement sandbox creation, reconnect, start/stop/shutdown, command execution, native file transfer, workspace persistence/hydration, and state serialization.
• Recreate a missing remote sandbox only when the SDK reports an explicit not-found response; other connection failures are propagated.
• Store the workspace root in the Harness WorkspaceSpec contract and expose it through OpenSandbox#getWorkspaceRoot().
• Keep the real-service smoke test opt-in: it runs only when both OPEN_SANDBOX_ENDPOINT and OPEN_SANDBOX_API_KEY are configured.
• Document configuration and usage in the English and Chinese Harness sandbox guides.

The branch has been synchronized with the current upstream main. Additional regression coverage exercises blank sandbox IDs, lifecycle idempotency and failure composition, bind-mount archive exclusions, temporary archive cleanup, option validation, SDK output normalization, and lazy official-client construction.

Testing

• OpenSandbox targeted suite: 47 tests passed, 0 failed, 1 opt-in real-service test skipped.
• mvn -B -T1 -pl agentscope-extensions/agentscope-extensions-sandbox/agentscope-extensions-sandbox-opensandbox -am verify -DskipTests: 6/6 reactor modules successful, including Spotless, compilation, Javadoc, and packaging.

Checklist

• Code has been formatted with mvn spotless:check
• OpenSandbox unit and serialization tests are passing
• Javadoc comments are complete and follow project conventions
• Related English and Chinese documentation has been updated
• Code is ready for review

[CLAassistant]

All committers have signed the CLA.

[codecov]

Codecov Report

❌ Patch coverage is 99.50495% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ensions/sandbox/opensandbox/OpenSandboxClient.java	98.33%	0 Missing and 1 partial ⚠️
...sions/sandbox/opensandbox/OpenSandboxEndpoint.java	92.85%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[AgentScopeJavaBot]

🤖 AI Review

This PR introduces a new OpenSandbox sandbox provider for the AgentScope Java SDK, enabling users to create and manage sandboxes through OpenSandbox Cloud's REST API. The implementation is well-structured with comprehensive test coverage, clean separation of concerns, and good documentation. The provider supports core sandbox lifecycle operations (create, start, stop, delete) and file operations, with proper error handling and timeout management.

Key strengths:

• Complete implementation following existing provider patterns (similar to E2B, Daytona)
• Comprehensive unit and integration tests with realistic mock scenarios
• Clean separation between API client, provider, state, and filesystem classes
• Good Javadoc documentation with usage examples

Areas for improvement:

• The OpenSandboxApiException class is defined but never actually used in the codebase (dead code)
• The retry logic in OpenSandboxApi.createSandbox() has a subtle bug where the retry loop condition is inverted
• The integration test OpenSandboxProviderIT makes real HTTP calls to localhost which will fail in CI environments
• The OpenSandboxSandboxState doesn't implement getWorkspaceRoot() which is needed by the harness runtime

(inline comments could not be attached — line numbers fell outside PR hunks. See archived report.)

[243006306]

有人审核下这个PR吗，想用这个功能

[jujn]

有人审核下这个PR吗，想用这个功能

可以本地打包帮试用下有无问题，暂时抽不出人力来审

[dargoner]

Addressed the review by checking each item against the current implementation and updating the branch to the latest upstream main.

• The referenced OpenSandboxApiException, OpenSandboxApi#createSandbox(), and OpenSandboxSandboxState symbols are not present in this PR. The implementation uses OpenSandbox, OpenSandboxSdk, and OpenSandboxState, so there is no unused API exception or inverted retry loop to remove/fix.
• Reconnection behavior is covered explicitly: a missing sandbox is recreated only after OpenSandboxSdk#isNotFound() returns true; generic connection failures are propagated without creating another sandbox.
• OpenSandboxIntegrationTest is an opt-in real-service smoke test. It is skipped unless both OPEN_SANDBOX_ENDPOINT and OPEN_SANDBOX_API_KEY are supplied, so the default CI run does not connect to localhost.
• The workspace root follows the Harness contract: it is stored in SandboxState.workspaceSpec.root, and OpenSandbox#getWorkspaceRoot() returns that value. Adding a second root field to OpenSandboxState would create two sources of truth.

I also added coverage for lifecycle, configuration, archive, and SDK edge cases. The previous Ubuntu CI failure was in JsonSessionDefaultLocationTest while closing the Harness test extension, outside this module; synchronizing the latest upstream main brings in the subsequent Harness test-cleanup changes.

Local verification after the update:

• OpenSandbox suite: 47 passed, 0 failed, 1 opt-in integration test skipped.
• OpenSandbox reactor verify with tests skipped: 6/6 modules built successfully, including formatting, compilation, Javadoc, and packaging.