mirror of
https://github.com/openai/codex.git
synced 2026-11-19 22:30:42 +00:00
## 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.
126 lines
4.5 KiB
Rust
126 lines
4.5 KiB
Rust
//! Resolve plugin namespace from skill file paths by walking ancestors for `plugin.json`.
|
|
|
|
use codex_exec_server::ExecutorFileSystem;
|
|
use codex_utils_absolute_path::AbsolutePathBuf;
|
|
use codex_utils_path_uri::PathUri;
|
|
use std::path::Path;
|
|
use std::path::PathBuf;
|
|
|
|
/// Ordered plugin manifest paths recognized beneath a plugin root.
|
|
pub const DISCOVERABLE_PLUGIN_MANIFEST_PATHS: &[&str] =
|
|
&[".codex-plugin/plugin.json", ".claude-plugin/plugin.json"];
|
|
|
|
pub fn find_plugin_manifest_path(plugin_root: &Path) -> Option<PathBuf> {
|
|
DISCOVERABLE_PLUGIN_MANIFEST_PATHS
|
|
.iter()
|
|
.map(|relative_path| plugin_root.join(relative_path))
|
|
.find(|manifest_path| manifest_path.is_file())
|
|
}
|
|
|
|
#[derive(serde::Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
struct RawPluginManifestName {
|
|
#[serde(default)]
|
|
name: String,
|
|
}
|
|
|
|
async fn plugin_manifest_name(
|
|
fs: &dyn ExecutorFileSystem,
|
|
plugin_root: &AbsolutePathBuf,
|
|
) -> Option<String> {
|
|
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).ok()?;
|
|
match fs.get_metadata(&candidate_uri, /*sandbox*/ None).await {
|
|
Ok(metadata) if metadata.is_file => {
|
|
manifest_path = Some(candidate);
|
|
break;
|
|
}
|
|
Ok(_) | Err(_) => {}
|
|
}
|
|
}
|
|
let manifest_path = manifest_path?;
|
|
let manifest_path_uri = PathUri::from_abs_path(&manifest_path).ok()?;
|
|
let contents = fs
|
|
.read_file_text(&manifest_path_uri, /*sandbox*/ None)
|
|
.await
|
|
.ok()?;
|
|
let RawPluginManifestName { name: raw_name } = serde_json::from_str(&contents).ok()?;
|
|
Some(
|
|
plugin_root
|
|
.file_name()
|
|
.and_then(|entry| entry.to_str())
|
|
.filter(|_| raw_name.trim().is_empty())
|
|
.unwrap_or(raw_name.as_str())
|
|
.to_string(),
|
|
)
|
|
}
|
|
|
|
/// Returns the plugin manifest `name` for the nearest ancestor of `path` that contains a valid
|
|
/// plugin manifest (same `name` rules as full manifest loading in codex-core).
|
|
pub async fn plugin_namespace_for_skill_path(
|
|
fs: &dyn ExecutorFileSystem,
|
|
path: &AbsolutePathBuf,
|
|
) -> Option<String> {
|
|
for ancestor in path.ancestors() {
|
|
if let Some(name) = plugin_manifest_name(fs, &ancestor).await {
|
|
return Some(name);
|
|
}
|
|
}
|
|
None
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::find_plugin_manifest_path;
|
|
use super::plugin_namespace_for_skill_path;
|
|
use codex_exec_server::LOCAL_FS;
|
|
use codex_utils_absolute_path::test_support::PathBufExt;
|
|
use std::fs;
|
|
use tempfile::tempdir;
|
|
|
|
const ALTERNATE_PLUGIN_MANIFEST_RELATIVE_PATH: &str = ".claude-plugin/plugin.json";
|
|
|
|
#[tokio::test]
|
|
async fn uses_manifest_name() {
|
|
let tmp = tempdir().expect("tempdir");
|
|
let plugin_root = tmp.path().join("plugins/sample");
|
|
let skill_path = plugin_root.join("skills/search/SKILL.md");
|
|
|
|
fs::create_dir_all(skill_path.parent().expect("parent")).expect("mkdir");
|
|
fs::create_dir_all(plugin_root.join(".codex-plugin")).expect("mkdir manifest");
|
|
fs::write(
|
|
plugin_root.join(".codex-plugin/plugin.json"),
|
|
r#"{"name":"sample"}"#,
|
|
)
|
|
.expect("write manifest");
|
|
fs::write(&skill_path, "---\ndescription: search\n---\n").expect("write skill");
|
|
|
|
assert_eq!(
|
|
plugin_namespace_for_skill_path(LOCAL_FS.as_ref(), &skill_path.abs()).await,
|
|
Some("sample".to_string())
|
|
);
|
|
}
|
|
|
|
#[tokio::test]
|
|
async fn uses_name_from_alternate_discoverable_manifest_path() {
|
|
let tmp = tempdir().expect("tempdir");
|
|
let plugin_root = tmp.path().join("plugins/sample");
|
|
let skill_path = plugin_root.join("skills/search/SKILL.md");
|
|
let manifest_path = plugin_root.join(ALTERNATE_PLUGIN_MANIFEST_RELATIVE_PATH);
|
|
|
|
fs::create_dir_all(skill_path.parent().expect("parent")).expect("mkdir");
|
|
fs::create_dir_all(manifest_path.parent().expect("manifest parent"))
|
|
.expect("mkdir manifest");
|
|
fs::write(&manifest_path, r#"{"name":"sample"}"#).expect("write manifest");
|
|
fs::write(&skill_path, "---\ndescription: search\n---\n").expect("write skill");
|
|
|
|
assert_eq!(
|
|
plugin_namespace_for_skill_path(LOCAL_FS.as_ref(), &skill_path.abs()).await,
|
|
Some("sample".to_string())
|
|
);
|
|
assert_eq!(find_plugin_manifest_path(&plugin_root), Some(manifest_path));
|
|
}
|
|
}
|