Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Define exec-server protocol types for streamed file writes (#49778)

Adam Perry @ OpenAI875bf9209bd9
diff --git a/codex-rs/exec-server-protocol/src/protocol.rs b/codex-rs/exec-server-protocol/src/protocol.rs
index 97402d5e12..738cd26144 100644
--- a/codex-rs/exec-server-protocol/src/protocol.rs
+++ b/codex-rs/exec-server-protocol/src/protocol.rs
@@ -35,6 +35,7 @@ pub const ENVIRONMENT_STATUS_METHOD: &str = "environment/status";
pub const FS_READ_FILE_METHOD: &str = "fs/readFile";
pub const FS_OPEN_METHOD: &str = "fs/open";
pub const FS_READ_BLOCK_METHOD: &str = "fs/readBlock";
+pub const FS_WRITE_BLOCK_METHOD: &str = "fs/writeBlock";
pub const FS_CLOSE_METHOD: &str = "fs/close";
pub const FS_WRITE_FILE_METHOD: &str = "fs/writeFile";
pub const FS_CREATE_DIRECTORY_METHOD: &str = "fs/createDirectory";
@@ -158,6 +159,9 @@ pub struct EnvironmentCapabilities {
/// Whether filesystem streams can use the requested platform sandbox.
#[serde(default)]
pub sandboxed_file_streaming: bool,
+ /// Whether `fs/open` supports replacement mode and `fs/writeBlock` is supported.
+ #[serde(default)]
+ pub file_write_streaming: bool,
/// Whether shell state can be cached and restored entirely inside the executor.
#[serde(default)]
pub shell_snapshot_v2: bool,
@@ -272,6 +276,7 @@ impl EnvironmentInfo {
environment_config_read: true,
http_header_env_vars: true,
sandboxed_file_streaming: true,
+ file_write_streaming: false,
shell_snapshot_v2: cfg!(unix),
windows_mxc,
linux_root_write_preserves_devices: cfg!(target_os = "linux"),
@@ -566,11 +571,24 @@ pub struct FsReadFileResponse {
pub data_base64: String,
}
+/// Defaults preserve read-only opens for legacy callers.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum FsOpenMode {
+ /// Open an existing file for reading.
+ #[default]
+ Read,
+ /// Open for writing, creating a missing file or truncating an existing file.
+ Replace,
+}
+
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct FsOpenParams {
pub handle_id: String,
pub path: PathUri,
+ #[serde(default)]
+ pub mode: FsOpenMode,
pub sandbox: Option<FileSystemSandboxContext>,
}
@@ -580,6 +598,8 @@ pub struct FsOpenParams {
pub struct WireFsOpenParams {
handle_id: String,
path: PathUri,
+ #[serde(default)]
+ mode: FsOpenMode,
sandbox: Option<WireFileSystemSandboxContext>,
}
@@ -604,6 +624,20 @@ pub struct FsReadBlockResponse {
pub eof: bool,
}
+/// Writes a nonempty block of at most [`codex_file_system::FILE_WRITE_CHUNK_SIZE`] decoded bytes at `offset`.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FsWriteBlockParams {
+ pub handle_id: String,
+ pub offset: u64,
+ pub chunk: ByteChunk,
+}
+
+/// A successful response confirms that every byte in the requested block was written.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FsWriteBlockResponse {}
+
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct FsCloseParams {
@@ -874,7 +908,7 @@ macro_rules! impl_wire_filesystem_request {
impl_wire_filesystem_request! {
WireFsReadFileParams => FsReadFileParams { path, follow_symlinks },
- WireFsOpenParams => FsOpenParams { handle_id, path },
+ WireFsOpenParams => FsOpenParams { handle_id, path, mode },
WireFsWriteFileParams => FsWriteFileParams { path, data_base64, follow_symlinks },
WireFsCreateDirectoryParams => FsCreateDirectoryParams { path, recursive, follow_symlinks },
WireFsGetMetadataParams => FsGetMetadataParams { path, follow_symlinks },
@@ -1201,6 +1235,7 @@ mod tests {
use super::ExecMetadata;
use super::ExecParams;
use super::ExecResponse;
+ use super::FsOpenMode;
use super::FsOpenParams;
use super::FsReadFileParams;
use super::HttpRequestParams;
@@ -1408,6 +1443,7 @@ mod tests {
environment_config_read: false,
http_header_env_vars: false,
sandboxed_file_streaming: false,
+ file_write_streaming: false,
shell_snapshot_v2: false,
windows_mxc: false,
linux_root_write_preserves_devices: false,
@@ -1468,6 +1504,7 @@ mod tests {
"environmentConfigRead": false,
"httpHeaderEnvVars": false,
"sandboxedFileStreaming": false,
+ "fileWriteStreaming": false,
"shellSnapshotV2": false,
"windowsMxc": false,
},
@@ -1737,6 +1774,26 @@ mod tests {
assert_eq!(request, params);
}
+ /// Legacy `fs/open` callers continue to open existing files for reading only.
+ #[test]
+ fn filesystem_open_accepts_legacy_request_without_mode() {
+ let wire: WireFsOpenParams = serde_json::from_value(serde_json::json!({
+ "handleId": "legacy-handle",
+ "path": "file:///tmp/existing.txt",
+ }))
+ .expect("legacy open should deserialize");
+ assert_eq!(
+ wire.try_into_request(|_| panic!("no sandbox to resolve"))
+ .expect("legacy open should resolve"),
+ FsOpenParams {
+ handle_id: "legacy-handle".to_string(),
+ path: PathUri::parse("file:///tmp/existing.txt").expect("file URI"),
+ mode: FsOpenMode::Read,
+ sandbox: None,
+ }
+ );
+ }
+
/// Only filesystem RPCs need the additive policy field; capability discovery keeps its original wire cwd.
#[test]
fn filesystem_open_and_capability_discovery_keep_their_existing_cwd_contracts() {
@@ -1750,6 +1807,7 @@ mod tests {
let open = FsOpenParams {
handle_id: "handle".to_owned(),
path: path.clone(),
+ mode: FsOpenMode::Read,
sandbox: Some(sandbox.clone()),
};
let capability = CapabilityRootDiscoverRequest {
diff --git a/codex-rs/exec-server/src/lib.rs b/codex-rs/exec-server/src/lib.rs
index b4fe4594fa..cde674dddf 100644
--- a/codex-rs/exec-server/src/lib.rs
+++ b/codex-rs/exec-server/src/lib.rs
@@ -87,6 +87,7 @@ pub use codex_file_system::EnvironmentAccessKey;
pub use codex_file_system::ExecutorFileSystem;
pub use codex_file_system::ExecutorFileSystemFuture;
pub use codex_file_system::FILE_READ_CHUNK_SIZE;
+pub use codex_file_system::FILE_WRITE_CHUNK_SIZE;
pub use codex_file_system::FileMetadata;
pub use codex_file_system::FileSystemEnvironmentAccessor;
pub use codex_file_system::FileSystemReadStream;
@@ -184,6 +185,7 @@ pub use protocol::FsCreateDirectoryParams;
pub use protocol::FsCreateDirectoryResponse;
pub use protocol::FsGetMetadataParams;
pub use protocol::FsGetMetadataResponse;
+pub use protocol::FsOpenMode;
pub use protocol::FsOpenParams;
pub use protocol::FsOpenResponse;
pub use protocol::FsReadBlockParams;
@@ -197,6 +199,8 @@ pub use protocol::FsRemoveParams;
pub use protocol::FsRemoveResponse;
pub use protocol::FsWalkParams;
pub use protocol::FsWalkResponse;
+pub use protocol::FsWriteBlockParams;
+pub use protocol::FsWriteBlockResponse;
pub use protocol::FsWriteFileParams;
pub use protocol::FsWriteFileResponse;
pub use protocol::HttpHeader;
diff --git a/codex-rs/exec-server/src/remote_file_stream.rs b/codex-rs/exec-server/src/remote_file_stream.rs
index f71e5fd1ee..f527becd91 100644
--- a/codex-rs/exec-server/src/remote_file_stream.rs
+++ b/codex-rs/exec-server/src/remote_file_stream.rs
@@ -11,6 +11,7 @@ use crate::FileSystemResult;
use crate::FileSystemSandboxContext;
use crate::protocol::FS_READ_BLOCK_METHOD;
use crate::protocol::FsCloseParams;
+use crate::protocol::FsOpenMode;
use crate::protocol::FsOpenParams;
use crate::protocol::FsReadBlockParams;
@@ -37,6 +38,7 @@ pub(super) async fn open(
.fs_open(FsOpenParams {
handle_id: registration.handle_id.clone(),
path,
+ mode: FsOpenMode::Read,
sandbox: sandbox.cloned(),
})
.await
diff --git a/codex-rs/exec-server/src/server/file_system_handler.rs b/codex-rs/exec-server/src/server/file_system_handler.rs
index 6f1c7c9847..a3cffcd0a2 100644
--- a/codex-rs/exec-server/src/server/file_system_handler.rs
+++ b/codex-rs/exec-server/src/server/file_system_handler.rs
@@ -28,6 +28,7 @@ use crate::protocol::FsCreateDirectoryParams;
use crate::protocol::FsCreateDirectoryResponse;
use crate::protocol::FsGetMetadataParams;
use crate::protocol::FsGetMetadataResponse;
+use crate::protocol::FsOpenMode;
use crate::protocol::FsOpenParams;
use crate::protocol::FsOpenResponse;
use crate::protocol::FsReadBlockParams;
@@ -122,6 +123,12 @@ impl FileSystemHandler {
params: FsOpenParams,
) -> Result<FsOpenResponse, JSONRPCErrorError> {
validate_file_handle_id(&params.handle_id)?;
+ // TODO(anp): Enable replacement opens when writable file streams are implemented.
+ if params.mode == FsOpenMode::Replace {
+ return Err(invalid_request(
+ "exec-server does not support writable file streams".to_string(),
+ ));
+ }
let file = self
.file_system
.open_file_for_read(&params.path, params.sandbox.as_ref())
diff --git a/codex-rs/exec-server/tests/file_stream.rs b/codex-rs/exec-server/tests/file_stream.rs
index 06cbfc3953..3d7cb11d2d 100644
--- a/codex-rs/exec-server/tests/file_stream.rs
+++ b/codex-rs/exec-server/tests/file_stream.rs
@@ -8,6 +8,7 @@ use codex_exec_server::ExecServerClient;
use codex_exec_server::ExecServerError;
use codex_exec_server::ExecutorFileSystem;
use codex_exec_server::FsCloseParams;
+use codex_exec_server::FsOpenMode;
use codex_exec_server::FsOpenParams;
use codex_exec_server::FsReadBlockParams;
use codex_exec_server::FsReadBlockResponse;
@@ -227,6 +228,7 @@ async fn read_block_supports_non_sequential_offsets_and_lengths() -> Result<()>
.fs_open(FsOpenParams {
handle_id: Uuid::new_v4().simple().to_string(),
path: PathUri::from_host_native_path(path)?,
+ mode: FsOpenMode::Read,
sandbox: None,
})
.await?;
@@ -293,6 +295,7 @@ async fn open_enforces_the_per_connection_limit_and_close_releases_capacity() ->
.fs_open(FsOpenParams {
handle_id: Uuid::new_v4().simple().to_string(),
path: path.clone(),
+ mode: FsOpenMode::Read,
sandbox: None,
})
.await?;
@@ -303,6 +306,7 @@ async fn open_enforces_the_per_connection_limit_and_close_releases_capacity() ->
.fs_open(FsOpenParams {
handle_id: Uuid::new_v4().simple().to_string(),
path: path.clone(),
+ mode: FsOpenMode::Read,
sandbox: None,
})
.await
@@ -327,6 +331,7 @@ async fn open_enforces_the_per_connection_limit_and_close_releases_capacity() ->
.fs_open(FsOpenParams {
handle_id: Uuid::new_v4().simple().to_string(),
path,
+ mode: FsOpenMode::Read,
sandbox: None,
})
.await?;
@@ -352,6 +357,7 @@ async fn open_rejects_handle_ids_longer_than_32_bytes() -> Result<()> {
.fs_open(FsOpenParams {
handle_id: "x".repeat(33),
path: PathUri::from_host_native_path(path)?,
+ mode: FsOpenMode::Read,
sandbox: None,
})
.await
diff --git a/codex-rs/file-system/src/lib.rs b/codex-rs/file-system/src/lib.rs
index cacff735cc..6edd302cf1 100644
--- a/codex-rs/file-system/src/lib.rs
+++ b/codex-rs/file-system/src/lib.rs
@@ -39,6 +39,8 @@ use std::task::Poll;
/// Maximum chunk size returned by [`ExecutorFileSystem::read_file_stream`].
pub const FILE_READ_CHUNK_SIZE: usize = 1024 * 1024;
+/// Maximum decoded chunk size accepted by a streamed filesystem write.
+pub const FILE_WRITE_CHUNK_SIZE: usize = 1024 * 1024;
/// Maximum accepted directory depth for a filesystem walk.
pub const MAX_WALK_DEPTH: usize = 64;
/// Maximum accepted directory count, including the walk root.