mirror of
https://github.com/pchuan98/codex.git
synced 2026-07-01 00:31:56 +08:00
Add executor-owned plugin resolution (#27692)
## Why
CCA can select a capability root that lives in an executor environment,
but
Codex only had a host-filesystem plugin loader. Before selected executor
plugins can contribute MCP servers, we need a small package boundary
that can
answer:
> Does this selected root contain a plugin, and if so, what does its
manifest
> declare?
The answer must come from the selected environment's filesystem. A
failed
executor lookup must never fall back to the orchestrator filesystem.
## What this changes
This PR introduces:
```rust
PluginProvider::resolve(root)
-> Result<Option<ResolvedPlugin>, Error>
```
`ExecutorPluginProvider` resolves one `SelectedCapabilityRoot` through
its
exact `environment_id`. It checks the recognized manifest locations,
reads the
manifest through that environment's `ExecutorFileSystem`, and returns an
inert
`ResolvedPlugin` containing:
- the opaque selected-root ID;
- the environment-bound plugin root;
- the authority-bound manifest resource;
- parsed metadata and authority-bound component locators.
Descriptor construction rejects manifest or component paths outside the
selected package root, so consumers cannot accidentally lose the package
boundary when they receive a resolved plugin.
If the root has no plugin manifest, resolution returns `None`, allowing
the
caller to treat it as a standalone capability such as a skill.
```text
selected root: repo -> env-1:/workspace/repo
|
| env-1 filesystem only
v
.codex-plugin/plugin.json
|
v
ResolvedPlugin { authority, root, manifest }
```
The existing host loader and the new executor provider now share the
same
manifest parser. Existing `codex-core-plugins::manifest` type paths
remain
available through re-exports, so host behavior and callers are
unchanged.
## Scope
This is intentionally a non-user-visible package-resolution PR. It does
not:
- parse or register plugin MCP server configurations;
- activate skills, connectors, hooks, or MCP servers;
- change app-server wiring;
- introduce host fallback, caching, or lifecycle behavior.
#27670 has merged, and this PR is now based directly on `main`. Together
with
the resolved MCP catalog from #27634, it establishes the inputs needed
for the
executor stdio MCP vertical without changing the existing MCP runtime.
## Follow-up
The next PR will consume `ResolvedPlugin`, read its declared/default MCP
config
through the same executor filesystem, bind supported stdio servers to
that
environment, and feed those registrations into the resolved MCP catalog.
An
app-server E2E will prove that selecting an executor plugin exposes and
invokes
its tool on the owning executor.
Resume/fork semantics, dynamic environment replacement, and non-stdio
placement remain separate lifecycle decisions.
## Validation
- `just fmt`
- `cargo check --tests -p codex-plugin -p codex-core-plugins`
- `just bazel-lock-check`
- `git diff --check`
Test targets were compiled but not executed locally; CI will run the
test and
Clippy suites.
This commit is contained in:
jif
GitHub
@@ -0,0 +1,232 @@
|
||||
use crate::manifest::parse_plugin_manifest;
|
||||
use codex_exec_server::EnvironmentManager;
|
||||
use codex_exec_server::ExecutorFileSystem;
|
||||
use codex_plugin::PluginProvider;
|
||||
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_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}`"
|
||||
)]
|
||||
UnavailableEnvironment {
|
||||
root_id: String,
|
||||
environment_id: String,
|
||||
},
|
||||
#[error("failed to inspect selected capability root `{root_id}` at {path}: {source}")]
|
||||
InspectRoot {
|
||||
root_id: String,
|
||||
path: AbsolutePathBuf,
|
||||
#[source]
|
||||
source: io::Error,
|
||||
},
|
||||
#[error("selected capability root `{root_id}` path {path} is not a directory")]
|
||||
RootNotDirectory {
|
||||
root_id: String,
|
||||
path: AbsolutePathBuf,
|
||||
},
|
||||
#[error("failed to inspect plugin manifest for `{root_id}` at {path}: {source}")]
|
||||
InspectManifest {
|
||||
root_id: String,
|
||||
path: AbsolutePathBuf,
|
||||
#[source]
|
||||
source: io::Error,
|
||||
},
|
||||
#[error("failed to read plugin manifest for `{root_id}` at {path}: {source}")]
|
||||
ReadManifest {
|
||||
root_id: String,
|
||||
path: AbsolutePathBuf,
|
||||
#[source]
|
||||
source: io::Error,
|
||||
},
|
||||
#[error("failed to parse plugin manifest for `{root_id}` at {path}: {source}")]
|
||||
ParseManifest {
|
||||
root_id: String,
|
||||
path: AbsolutePathBuf,
|
||||
#[source]
|
||||
source: serde_json::Error,
|
||||
},
|
||||
#[error("failed to construct plugin descriptor for `{root_id}`: {source}")]
|
||||
ConstructDescriptor {
|
||||
root_id: String,
|
||||
#[source]
|
||||
source: ResolvedPluginError,
|
||||
},
|
||||
}
|
||||
|
||||
/// Resolves plugin packages through the filesystem owned by an execution environment.
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct ExecutorPluginProvider {
|
||||
environment_manager: Arc<EnvironmentManager>,
|
||||
}
|
||||
|
||||
impl ExecutorPluginProvider {
|
||||
/// Creates a provider backed by the active execution environments.
|
||||
pub fn new(environment_manager: Arc<EnvironmentManager>) -> Self {
|
||||
Self {
|
||||
environment_manager,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl PluginProvider for ExecutorPluginProvider {
|
||||
type Error = ExecutorPluginProviderError;
|
||||
|
||||
async fn resolve(
|
||||
&self,
|
||||
selected_root: &SelectedCapabilityRoot,
|
||||
) -> Result<Option<ResolvedPlugin>, Self::Error> {
|
||||
let root_id = &selected_root.id;
|
||||
let plugin_root = selected_plugin_root(selected_root)?;
|
||||
let CapabilityRootLocation::Environment { environment_id, .. } = &selected_root.location;
|
||||
let environment = self
|
||||
.environment_manager
|
||||
.get_environment(environment_id)
|
||||
.ok_or_else(|| ExecutorPluginProviderError::UnavailableEnvironment {
|
||||
root_id: root_id.clone(),
|
||||
environment_id: environment_id.clone(),
|
||||
})?;
|
||||
let file_system = environment.get_filesystem();
|
||||
|
||||
resolve_plugin_root(selected_root, plugin_root, file_system.as_ref()).await
|
||||
}
|
||||
}
|
||||
|
||||
fn selected_plugin_root(
|
||||
selected_root: &SelectedCapabilityRoot,
|
||||
) -> Result<AbsolutePathBuf, ExecutorPluginProviderError> {
|
||||
let root_id = &selected_root.id;
|
||||
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(),
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
async fn resolve_plugin_root(
|
||||
selected_root: &SelectedCapabilityRoot,
|
||||
plugin_root: AbsolutePathBuf,
|
||||
file_system: &dyn ExecutorFileSystem,
|
||||
) -> Result<Option<ResolvedPlugin>, ExecutorPluginProviderError> {
|
||||
let root_id = &selected_root.id;
|
||||
let CapabilityRootLocation::Environment {
|
||||
environment_id,
|
||||
path,
|
||||
} = &selected_root.location;
|
||||
let root_uri = PathUri::from_abs_path(&plugin_root).map_err(|err| {
|
||||
ExecutorPluginProviderError::InvalidRootPath {
|
||||
root_id: root_id.clone(),
|
||||
path: path.clone(),
|
||||
message: err.to_string(),
|
||||
}
|
||||
})?;
|
||||
let root_metadata = file_system
|
||||
.get_metadata(&root_uri, /*sandbox*/ None)
|
||||
.await
|
||||
.map_err(|source| ExecutorPluginProviderError::InspectRoot {
|
||||
root_id: root_id.clone(),
|
||||
path: plugin_root.clone(),
|
||||
source,
|
||||
})?;
|
||||
if !root_metadata.is_directory {
|
||||
return Err(ExecutorPluginProviderError::RootNotDirectory {
|
||||
root_id: root_id.clone(),
|
||||
path: 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).map_err(|err| {
|
||||
ExecutorPluginProviderError::InvalidRootPath {
|
||||
root_id: root_id.clone(),
|
||||
path: candidate.as_path().to_string_lossy().into_owned(),
|
||||
message: err.to_string(),
|
||||
}
|
||||
})?;
|
||||
match file_system
|
||||
.get_metadata(&candidate_uri, /*sandbox*/ None)
|
||||
.await
|
||||
{
|
||||
Ok(metadata) if metadata.is_file => {
|
||||
manifest_path = Some((candidate, candidate_uri));
|
||||
break;
|
||||
}
|
||||
Ok(_) => {}
|
||||
Err(err) if err.kind() == io::ErrorKind::NotFound => {}
|
||||
Err(source) => {
|
||||
return Err(ExecutorPluginProviderError::InspectManifest {
|
||||
root_id: root_id.clone(),
|
||||
path: candidate,
|
||||
source,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
let Some((manifest_path, manifest_uri)) = manifest_path else {
|
||||
return Ok(None);
|
||||
};
|
||||
let contents = file_system
|
||||
.read_file_text(&manifest_uri, /*sandbox*/ None)
|
||||
.await
|
||||
.map_err(|source| ExecutorPluginProviderError::ReadManifest {
|
||||
root_id: root_id.clone(),
|
||||
path: manifest_path.clone(),
|
||||
source,
|
||||
})?;
|
||||
let manifest =
|
||||
parse_plugin_manifest(&plugin_root, &manifest_path, &contents).map_err(|source| {
|
||||
ExecutorPluginProviderError::ParseManifest {
|
||||
root_id: root_id.clone(),
|
||||
path: manifest_path.clone(),
|
||||
source,
|
||||
}
|
||||
})?;
|
||||
|
||||
let plugin = ResolvedPlugin::from_environment(
|
||||
root_id.clone(),
|
||||
environment_id.clone(),
|
||||
plugin_root,
|
||||
manifest_path,
|
||||
manifest,
|
||||
)
|
||||
.map_err(|source| ExecutorPluginProviderError::ConstructDescriptor {
|
||||
root_id: root_id.clone(),
|
||||
source,
|
||||
})?;
|
||||
|
||||
Ok(Some(plugin))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
#[path = "provider_tests.rs"]
|
||||
mod tests;
|
||||
Reference in New Issue
Block a user