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

## What changed

- Add `read` and `replace` modes to `fs/open`, defaulting omitted modes to `read` for existing callers.
- Define `fs/writeBlock` request and response types for offset-based writes, with a maximum decoded chunk size of 1 MiB.
- Add the `fileWriteStreaming` capability, defaulting to `false`. Keep writable streams unsupported in the server and explicitly reject replacement opens.

## Testing

Add a protocol test verifying that legacy `fs/open` requests without a mode deserialize as read-only opens.

GitOrigin-RevId: 4d3997717e821cd1f62df12a03c8eec36332a66d

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 {