Description
Currently, the agent-sandbox has independent client implementations in Go and Python. To ensure interoperability, reduce maintenance overhead, and provide a "source of truth" for the sandbox API, we need to establish a common contract using Protocol Buffers (Protobuf) and gRPC.
Beyond the interface definition, we also need to document the behavioral expectations that aren't easily captured in a .proto file (e.g., how we handle paths, telemetry, and resource constraints).
Scope of Work
1. Protobuf Definition (/proto)
- Define the core service interface (e.g.,
AgentSandboxService).
- Standardize Request/Response messages for agent lifecycle management.
- Establish common error codes using gRPC status codes (e.g.,
INVALID_ARGUMENT for malformed paths).
2. Behavioral Specification (The "Unwritten" Rules)
We need to document the following in a spec/behavior.md or similar shared document:
- Path Validation: Strict rules on absolute vs. relative paths to prevent directory traversal within the sandbox.
- Response Size Limits: Maximum byte size for stdout/stderr streams or file transfers to prevent OOM in the controller.
- OTel Scoping: Standardized attribute keys for OpenTelemetry (e.g.,
sandbox.id) so traces are consistent across Go and Python.
- Retry Policy: Default exponential backoff parameters for transient network failures.
3. Tooling & CI
- Integrate
buf for linting and breaking change detection.
- Setup generation scripts to sync the generated code to the respective
/clients directories.
Implementation Plan
Additional Context
Establishing this contract now prevents "implementation drift" where the Python client might support a feature (like partial file reads) that the Go client handles differently.
Description
Currently, the
agent-sandboxhas independent client implementations in Go and Python. To ensure interoperability, reduce maintenance overhead, and provide a "source of truth" for the sandbox API, we need to establish a common contract using Protocol Buffers (Protobuf) and gRPC.Beyond the interface definition, we also need to document the behavioral expectations that aren't easily captured in a
.protofile (e.g., how we handle paths, telemetry, and resource constraints).Scope of Work
1. Protobuf Definition (
/proto)AgentSandboxService).INVALID_ARGUMENTfor malformed paths).2. Behavioral Specification (The "Unwritten" Rules)
We need to document the following in a
spec/behavior.mdor similar shared document:sandbox.id) so traces are consistent across Go and Python.3. Tooling & CI
buffor linting and breaking change detection./clientsdirectories.Implementation Plan
.protofile and aCONFORMANCE.mddoc.buf lint.Additional Context
Establishing this contract now prevents "implementation drift" where the Python client might support a feature (like partial file reads) that the Go client handles differently.