Make selected plugin roots URI-native (#28918)

## Why Selected capability roots belong to the executor filesystem, not the app-server host. Converting their path strings into the host's native `Path` breaks whenever the two machines use different path conventions, such as a Windows executor behind a Unix app-server. This PR establishes `PathUri` as the selected-plugin boundary so the executor remains authoritative for its paths. ## What changed - Require `selectedCapabilityRoots[].location.path` to be a canonical `file:` URI and deserialize it directly as `PathUri`; native path strings are rejected. - Update the app-server schema, generated TypeScript, examples, and request coverage for the URI contract. - Keep selected roots, resolved plugin locations, manifest paths, and manifest resources as `PathUri`. - Inspect and read plugin roots and manifests only through the selected environment's `ExecutorFileSystem`. - Parse executor manifests with the shared URI-native parser from #29620 instead of projecting them onto the host filesystem. - Enforce resource containment lexically and preserve the root URI's POSIX or Windows path convention. - Cover foreign Windows plugin roots and URI-native manifest resources. ```text thread/start selectedCapabilityRoots[].location.path = "file:///C:/plugins/demo" | PathUri v ExecutorFileSystem | +--> plugin.json +--> manifest resources ``` This PR stops at the shared selected-plugin representation. The next two PRs remove the remaining host-path projections in the skill and MCP consumers. ## Stack 1. #29614 — add lexical `PathUri` containment. 2. #29620 — share URI-native manifest path resolution. 3. **This PR** — keep selected plugin roots and resources URI-native. 4. #29626 — load executor skills without host path conversion. 5. #29628 — resolve executor MCP working directories without host path conversion.
2026-07-01 00:31:56 +08:00 · 2026-06-23 22:51:19 +01:00
parent 01f89c8c59
commit 2e69966cd8
25 changed files with 409 additions and 197 deletions
@@ -1,6 +1,6 @@
 use crate::manifest::PluginManifest;
 use codex_protocol::capabilities::SelectedCapabilityRoot;
-use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_path_uri::PathUri;
 use std::error::Error as StdError;
 use std::future::Future;
 use thiserror::Error;
@@ -11,8 +11,8 @@ pub enum PluginResourceLocator {
    Environment {
        /// Environment whose filesystem owns the resource.
        environment_id: String,
-        /// Absolute resource path within that filesystem.
-        path: AbsolutePathBuf,
+        /// Resource URI within that filesystem.
+        path: PathUri,
    },
 }

@@ -22,8 +22,8 @@ pub enum ResolvedPluginLocation {
    Environment {
        /// Environment whose filesystem owns the package.
        environment_id: String,
-        /// Absolute package root within that filesystem.
-        root: AbsolutePathBuf,
+        /// Package root URI within that filesystem.
+        root: PathUri,
    },
 }

@@ -40,10 +40,7 @@ pub struct ResolvedPlugin {
 #[derive(Clone, Debug, Error, PartialEq, Eq)]
 pub enum ResolvedPluginError {
    #[error("plugin resource path `{path}` is outside package root `{root}`")]
-    ResourceOutsideRoot {
-        root: AbsolutePathBuf,
-        path: AbsolutePathBuf,
-    },
+    ResourceOutsideRoot { root: PathUri, path: PathUri },
 }

 impl ResolvedPlugin {
@@ -51,9 +48,9 @@ impl ResolvedPlugin {
    pub fn from_environment(
        selected_root_id: String,
        environment_id: String,
-        root: AbsolutePathBuf,
-        manifest_path: AbsolutePathBuf,
-        manifest: PluginManifest<AbsolutePathBuf>,
+        root: PathUri,
+        manifest_path: PathUri,
+        manifest: PluginManifest<PathUri>,
    ) -> Result<Self, ResolvedPluginError> {
        let manifest_path = environment_resource(&environment_id, &root, manifest_path)?;
        let manifest = manifest
@@ -92,10 +89,10 @@ impl ResolvedPlugin {

 fn environment_resource(
    environment_id: &str,
-    root: &AbsolutePathBuf,
-    path: AbsolutePathBuf,
+    root: &PathUri,
+    path: PathUri,
 ) -> Result<PluginResourceLocator, ResolvedPluginError> {
-    if !path.as_path().starts_with(root.as_path()) {
+    if !path.starts_with(root) {
        return Err(ResolvedPluginError::ResourceOutsideRoot {
            root: root.clone(),
            path,
@@ -7,22 +7,28 @@ use crate::manifest::PluginManifestInterface;
 use crate::manifest::PluginManifestMcpServers;
 use crate::manifest::PluginManifestPaths;
 use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_path_uri::PathUri;
 use pretty_assertions::assert_eq;

 fn absolute(path: impl AsRef<std::path::Path>) -> AbsolutePathBuf {
    AbsolutePathBuf::from_absolute_path_checked(path.as_ref()).expect("absolute test path")
 }

-fn resource(environment_id: &str, path: AbsolutePathBuf) -> PluginResourceLocator {
+fn path_uri(path: &AbsolutePathBuf) -> PathUri {
+    PathUri::from_abs_path(path)
+}
+
+fn resource(environment_id: &str, path: &AbsolutePathBuf) -> PluginResourceLocator {
    PluginResourceLocator::Environment {
        environment_id: environment_id.to_string(),
-        path,
+        path: path_uri(path),
    }
 }

 #[test]
 fn environment_descriptor_binds_every_manifest_resource() {
    let root = absolute(std::env::current_dir().expect("cwd").join("plugin-root"));
+    let root_uri = path_uri(&root);
    let manifest_path = root.join(".codex-plugin/plugin.json");
    let skills = root.join("skills");
    let mcp_servers = root.join(".mcp.json");
@@ -37,15 +43,15 @@ fn environment_descriptor_binds_every_manifest_resource() {
        description: None,
        keywords: Vec::new(),
        paths: PluginManifestPaths {
-            skills: vec![skills.clone()],
-            mcp_servers: Some(PluginManifestMcpServers::Path(mcp_servers.clone())),
-            apps: Some(apps.clone()),
-            hooks: Some(PluginManifestHooks::Paths(vec![hooks.clone()])),
+            skills: vec![path_uri(&skills)],
+            mcp_servers: Some(PluginManifestMcpServers::Path(path_uri(&mcp_servers))),
+            apps: Some(path_uri(&apps)),
+            hooks: Some(PluginManifestHooks::Paths(vec![path_uri(&hooks)])),
        },
        interface: Some(PluginManifestInterface {
-            composer_icon: Some(composer_icon.clone()),
-            logo: Some(logo.clone()),
-            screenshots: vec![screenshot.clone()],
+            composer_icon: Some(path_uri(&composer_icon)),
+            logo: Some(path_uri(&logo)),
+            screenshots: vec![path_uri(&screenshot)],
            ..PluginManifestInterface::default()
        }),
    };
@@ -53,15 +59,15 @@ fn environment_descriptor_binds_every_manifest_resource() {
    let plugin = ResolvedPlugin::from_environment(
        "selected-demo".to_string(),
        "executor-1".to_string(),
-        root,
-        manifest_path.clone(),
+        root_uri,
+        path_uri(&manifest_path),
        manifest,
    )
    .expect("valid descriptor");

    assert_eq!(
        plugin.manifest_path(),
-        &resource("executor-1", manifest_path)
+        &resource("executor-1", &manifest_path)
    );
    assert_eq!(
        plugin.manifest(),
@@ -71,21 +77,21 @@ fn environment_descriptor_binds_every_manifest_resource() {
            description: None,
            keywords: Vec::new(),
            paths: PluginManifestPaths {
-                skills: vec![resource("executor-1", skills)],
+                skills: vec![resource("executor-1", &skills)],
                mcp_servers: Some(PluginManifestMcpServers::Path(resource(
                    "executor-1",
-                    mcp_servers,
+                    &mcp_servers,
                ))),
-                apps: Some(resource("executor-1", apps)),
+                apps: Some(resource("executor-1", &apps)),
                hooks: Some(PluginManifestHooks::Paths(vec![resource(
                    "executor-1",
-                    hooks,
+                    &hooks
                )])),
            },
            interface: Some(PluginManifestInterface {
-                composer_icon: Some(resource("executor-1", composer_icon)),
-                logo: Some(resource("executor-1", logo)),
-                screenshots: vec![resource("executor-1", screenshot)],
+                composer_icon: Some(resource("executor-1", &composer_icon)),
+                logo: Some(resource("executor-1", &logo)),
+                screenshots: vec![resource("executor-1", &screenshot)],
                ..PluginManifestInterface::default()
            }),
        }
@@ -104,7 +110,7 @@ fn environment_descriptor_rejects_resources_outside_package_root() {
        keywords: Vec::new(),
        paths: PluginManifestPaths {
            skills: Vec::new(),
-            mcp_servers: Some(PluginManifestMcpServers::Path(outside.clone())),
+            mcp_servers: Some(PluginManifestMcpServers::Path(path_uri(&outside))),
            apps: None,
            hooks: None,
        },
@@ -114,8 +120,8 @@ fn environment_descriptor_rejects_resources_outside_package_root() {
    let err = ResolvedPlugin::from_environment(
        "selected-demo".to_string(),
        "executor-1".to_string(),
-        root.clone(),
-        root.join(".codex-plugin/plugin.json"),
+        path_uri(&root),
+        path_uri(&root.join(".codex-plugin/plugin.json")),
        manifest,
    )
    .expect_err("outside resource should fail");
@@ -123,8 +129,8 @@ fn environment_descriptor_rejects_resources_outside_package_root() {
    assert_eq!(
        err,
        ResolvedPluginError::ResourceOutsideRoot {
-            root,
-            path: outside,
+            root: path_uri(&root),
+            path: path_uri(&outside),
        }
    );
 }