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.
This commit is contained in:
jif authored and GitHub committed 2026-06-23 22:51:19 +01:00
1 parent 01f89c8c59
commit 2e69966cd8
25 files changed
+409 -197

No files matched your search

+35 -47
View File
@@ -1,4 +1,4 @@
use crate::manifest::parse_plugin_manifest;
use crate::manifest::parse_plugin_manifest_uri;
use codex_exec_server::EnvironmentManager;
use codex_exec_server::ExecutorFileSystem;
use codex_plugin::PluginProvider;
@@ -6,23 +6,16 @@ use codex_plugin::ResolvedPlugin;
use codex_plugin::ResolvedPluginError;
use codex_protocol::capabilities::CapabilityRootLocation;
use codex_protocol::capabilities::SelectedCapabilityRoot;
use codex_utils_absolute_path::AbsolutePathBuf;
use codex_utils_path_uri::PathUri;
use codex_utils_path_uri::PathUriParseError;
use codex_utils_plugins::DISCOVERABLE_PLUGIN_MANIFEST_PATHS;
use std::io;
use std::path::PathBuf;
use std::sync::Arc;
use thiserror::Error;
/// Failure to resolve an environment-owned capability root as a plugin package.
#[derive(Debug, Error)]
pub enum ExecutorPluginProviderError {
#[error("selected capability root `{root_id}` has invalid path `{path}`: {message}")]
InvalidRootPath {
root_id: String,
path: String,
message: String,
},
#[error(
"selected capability root `{root_id}` references unavailable environment `{environment_id}`"
)]
@@ -33,33 +26,40 @@ pub enum ExecutorPluginProviderError {
#[error("failed to inspect selected capability root `{root_id}` at {path}: {source}")]
InspectRoot {
root_id: String,
path: AbsolutePathBuf,
path: PathUri,
#[source]
source: io::Error,
},
#[error("selected capability root `{root_id}` path {path} is not a directory")]
RootNotDirectory {
RootNotDirectory { root_id: String, path: PathUri },
#[error(
"failed to resolve plugin manifest path `{relative_path}` below selected capability root `{root_id}` at {root}: {source}"
)]
InvalidManifestPath {
root_id: String,
path: AbsolutePathBuf,
root: PathUri,
relative_path: &'static str,
#[source]
source: PathUriParseError,
},
#[error("failed to inspect plugin manifest for `{root_id}` at {path}: {source}")]
InspectManifest {
root_id: String,
path: AbsolutePathBuf,
path: PathUri,
#[source]
source: io::Error,
},
#[error("failed to read plugin manifest for `{root_id}` at {path}: {source}")]
ReadManifest {
root_id: String,
path: AbsolutePathBuf,
path: PathUri,
#[source]
source: io::Error,
},
#[error("failed to parse plugin manifest for `{root_id}` at {path}: {source}")]
ParseManifest {
root_id: String,
path: AbsolutePathBuf,
path: PathUri,
#[source]
source: serde_json::Error,
},
@@ -110,7 +110,7 @@ impl ExecutorPluginProvider {
selected_root: &SelectedCapabilityRoot,
) -> Result<Option<ResolvedExecutorPlugin>, ExecutorPluginProviderError> {
let root_id = &selected_root.id;
let plugin_root = selected_plugin_root(selected_root)?;
let plugin_root = selected_plugin_root(selected_root);
let CapabilityRootLocation::Environment { environment_id, .. } = &selected_root.location;
let environment = self
.environment_manager
@@ -142,38 +142,20 @@ impl PluginProvider for ExecutorPluginProvider {
}
}
fn selected_plugin_root(
selected_root: &SelectedCapabilityRoot,
) -> Result<AbsolutePathBuf, ExecutorPluginProviderError> {
let root_id = &selected_root.id;
fn selected_plugin_root(selected_root: &SelectedCapabilityRoot) -> PathUri {
let CapabilityRootLocation::Environment { path, .. } = &selected_root.location;
let plugin_root = PathBuf::from(path);
if !plugin_root.is_absolute() {
return Err(ExecutorPluginProviderError::InvalidRootPath {
root_id: root_id.clone(),
path: path.clone(),
message: "executor path must be absolute".to_string(),
});
}
AbsolutePathBuf::from_absolute_path_checked(plugin_root).map_err(|err| {
ExecutorPluginProviderError::InvalidRootPath {
root_id: root_id.clone(),
path: path.clone(),
message: err.to_string(),
}
})
path.clone()
}
async fn resolve_plugin_root(
selected_root: &SelectedCapabilityRoot,
plugin_root: AbsolutePathBuf,
plugin_root: PathUri,
file_system: &dyn ExecutorFileSystem,
) -> Result<Option<ResolvedPlugin>, ExecutorPluginProviderError> {
let root_id = &selected_root.id;
let CapabilityRootLocation::Environment { environment_id, .. } = &selected_root.location;
let root_uri = PathUri::from_abs_path(&plugin_root);
let root_metadata = file_system
.get_metadata(&root_uri, /*sandbox*/ None)
.get_metadata(&plugin_root, /*sandbox*/ None)
.await
.map_err(|source| ExecutorPluginProviderError::InspectRoot {
root_id: root_id.clone(),
@@ -189,14 +171,20 @@ async fn resolve_plugin_root(
let mut manifest_path = None;
for relative_path in DISCOVERABLE_PLUGIN_MANIFEST_PATHS {
let candidate = plugin_root.join(relative_path);
let candidate_uri = PathUri::from_abs_path(&candidate);
let candidate_uri = plugin_root.join(relative_path).map_err(|source| {
ExecutorPluginProviderError::InvalidManifestPath {
root_id: root_id.clone(),
root: plugin_root.clone(),
relative_path,
source,
}
})?;
match file_system
.get_metadata(&candidate_uri, /*sandbox*/ None)
.await
{
Ok(metadata) if metadata.is_file => {
manifest_path = Some((candidate, candidate_uri));
manifest_path = Some(candidate_uri);
break;
}
Ok(_) => {}
@@ -204,13 +192,13 @@ async fn resolve_plugin_root(
Err(source) => {
return Err(ExecutorPluginProviderError::InspectManifest {
root_id: root_id.clone(),
path: candidate,
path: candidate_uri,
source,
});
}
}
}
let Some((manifest_path, manifest_uri)) = manifest_path else {
let Some(manifest_uri) = manifest_path else {
return Ok(None);
};
let contents = file_system
@@ -218,14 +206,14 @@ async fn resolve_plugin_root(
.await
.map_err(|source| ExecutorPluginProviderError::ReadManifest {
root_id: root_id.clone(),
path: manifest_path.clone(),
path: manifest_uri.clone(),
source,
})?;
let manifest =
parse_plugin_manifest(&plugin_root, &manifest_path, &contents).map_err(|source| {
parse_plugin_manifest_uri(&plugin_root, &manifest_uri, &contents).map_err(|source| {
ExecutorPluginProviderError::ParseManifest {
root_id: root_id.clone(),
path: manifest_path.clone(),
path: manifest_uri.clone(),
source,
}
})?;
@@ -234,7 +222,7 @@ async fn resolve_plugin_root(
root_id.clone(),
environment_id.clone(),
plugin_root,
manifest_path,
manifest_uri,
manifest,
)
.map_err(|source| ExecutorPluginProviderError::ConstructDescriptor {