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.

codex-rs/plugin/src/lib.rs

@@ -1,10 +1,12 @@
-//! Shared plugin identifiers and telemetry-facing summaries.
+//! Shared plugin package models, source providers, identifiers, and telemetry summaries.
 
 pub use codex_utils_plugins::mention_syntax;
 pub use codex_utils_plugins::plugin_namespace_for_skill_path;
 
 mod load_outcome;
+pub mod manifest;
 mod plugin_id;
+mod provider;
 
 use codex_config::HookEventsToml;
 use codex_utils_absolute_path::AbsolutePathBuf;
@@ -15,6 +17,11 @@ pub use load_outcome::prompt_safe_plugin_description;
 pub use plugin_id::PluginId;
 pub use plugin_id::PluginIdError;
 pub use plugin_id::validate_plugin_segment;
+pub use provider::PluginProvider;
+pub use provider::PluginResourceLocator;
+pub use provider::ResolvedPlugin;
+pub use provider::ResolvedPluginError;
+pub use provider::ResolvedPluginLocation;
 
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct AppConnectorId(pub String);

codex-rs/plugin/src/manifest.rs

@@ -0,0 +1,157 @@
+use codex_config::HooksFile;
+
+/// Parsed plugin metadata parameterized by its resource locator representation.
+///
+/// Host loading uses absolute paths, while resolved packages replace them with
+/// authority-bound locators before exposing the manifest to consumers.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginManifest<Resource> {
+    pub name: String,
+    pub version: Option<String>,
+    pub description: Option<String>,
+    pub keywords: Vec<String>,
+    pub paths: PluginManifestPaths<Resource>,
+    pub interface: Option<PluginManifestInterface<Resource>>,
+}
+
+/// Component resources declared by a plugin manifest.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginManifestPaths<Resource> {
+    pub skills: Option<Resource>,
+    pub mcp_servers: Option<Resource>,
+    pub apps: Option<Resource>,
+    pub hooks: Option<PluginManifestHooks<Resource>>,
+}
+
+/// Hook declarations embedded in or referenced by a plugin manifest.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum PluginManifestHooks<Resource> {
+    Paths(Vec<Resource>),
+    Inline(Vec<HooksFile>),
+}
+
+/// Optional model- and UI-facing plugin metadata.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginManifestInterface<Resource> {
+    pub display_name: Option<String>,
+    pub short_description: Option<String>,
+    pub long_description: Option<String>,
+    pub developer_name: Option<String>,
+    pub category: Option<String>,
+    pub capabilities: Vec<String>,
+    pub website_url: Option<String>,
+    pub privacy_policy_url: Option<String>,
+    pub terms_of_service_url: Option<String>,
+    pub default_prompt: Option<Vec<String>>,
+    pub brand_color: Option<String>,
+    pub composer_icon: Option<Resource>,
+    pub logo: Option<Resource>,
+    pub screenshots: Vec<Resource>,
+}
+
+impl<Resource> Default for PluginManifestInterface<Resource> {
+    fn default() -> Self {
+        Self {
+            display_name: None,
+            short_description: None,
+            long_description: None,
+            developer_name: None,
+            category: None,
+            capabilities: Vec::new(),
+            website_url: None,
+            privacy_policy_url: None,
+            terms_of_service_url: None,
+            default_prompt: None,
+            brand_color: None,
+            composer_icon: None,
+            logo: None,
+            screenshots: Vec::new(),
+        }
+    }
+}
+
+impl<Resource> PluginManifest<Resource> {
+    pub(crate) fn try_map_resources<Mapped, Error>(
+        self,
+        mut map: impl FnMut(Resource) -> Result<Mapped, Error>,
+    ) -> Result<PluginManifest<Mapped>, Error> {
+        let PluginManifest {
+            name,
+            version,
+            description,
+            keywords,
+            paths,
+            interface,
+        } = self;
+        let PluginManifestPaths {
+            skills,
+            mcp_servers,
+            apps,
+            hooks,
+        } = paths;
+        let hooks = match hooks {
+            Some(PluginManifestHooks::Paths(paths)) => Some(PluginManifestHooks::Paths(
+                paths
+                    .into_iter()
+                    .map(&mut map)
+                    .collect::<Result<Vec<_>, _>>()?,
+            )),
+            Some(PluginManifestHooks::Inline(hooks)) => Some(PluginManifestHooks::Inline(hooks)),
+            None => None,
+        };
+        let interface = match interface {
+            Some(interface) => {
+                let PluginManifestInterface {
+                    display_name,
+                    short_description,
+                    long_description,
+                    developer_name,
+                    category,
+                    capabilities,
+                    website_url,
+                    privacy_policy_url,
+                    terms_of_service_url,
+                    default_prompt,
+                    brand_color,
+                    composer_icon,
+                    logo,
+                    screenshots,
+                } = interface;
+                Some(PluginManifestInterface {
+                    display_name,
+                    short_description,
+                    long_description,
+                    developer_name,
+                    category,
+                    capabilities,
+                    website_url,
+                    privacy_policy_url,
+                    terms_of_service_url,
+                    default_prompt,
+                    brand_color,
+                    composer_icon: composer_icon.map(&mut map).transpose()?,
+                    logo: logo.map(&mut map).transpose()?,
+                    screenshots: screenshots
+                        .into_iter()
+                        .map(&mut map)
+                        .collect::<Result<Vec<_>, _>>()?,
+                })
+            }
+            None => None,
+        };
+
+        Ok(PluginManifest {
+            name,
+            version,
+            description,
+            keywords,
+            paths: PluginManifestPaths {
+                skills: skills.map(&mut map).transpose()?,
+                mcp_servers: mcp_servers.map(&mut map).transpose()?,
+                apps: apps.map(&mut map).transpose()?,
+                hooks,
+            },
+            interface,
+        })
+    }
+}

codex-rs/plugin/src/provider.rs

@@ -0,0 +1,128 @@
+use crate::manifest::PluginManifest;
+use codex_protocol::capabilities::SelectedCapabilityRoot;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use std::error::Error as StdError;
+use std::future::Future;
+use thiserror::Error;
+
+/// A plugin resource paired with the environment that owns its filesystem.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum PluginResourceLocator {
+    Environment {
+        /// Environment whose filesystem owns the resource.
+        environment_id: String,
+        /// Absolute resource path within that filesystem.
+        path: AbsolutePathBuf,
+    },
+}
+
+/// Authority-bound location of a resolved plugin package.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ResolvedPluginLocation {
+    Environment {
+        /// Environment whose filesystem owns the package.
+        environment_id: String,
+        /// Absolute package root within that filesystem.
+        root: AbsolutePathBuf,
+    },
+}
+
+/// An inert plugin descriptor whose resources retain their source authority.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ResolvedPlugin {
+    selected_root_id: String,
+    location: ResolvedPluginLocation,
+    manifest_path: PluginResourceLocator,
+    manifest: PluginManifest<PluginResourceLocator>,
+}
+
+/// Failure to construct a resolved plugin with internally consistent resources.
+#[derive(Clone, Debug, Error, PartialEq, Eq)]
+pub enum ResolvedPluginError {
+    #[error("plugin resource path `{path}` is outside package root `{root}`")]
+    ResourceOutsideRoot {
+        root: AbsolutePathBuf,
+        path: AbsolutePathBuf,
+    },
+}
+
+impl ResolvedPlugin {
+    /// Creates an environment-owned descriptor from a validated plugin manifest.
+    pub fn from_environment(
+        selected_root_id: String,
+        environment_id: String,
+        root: AbsolutePathBuf,
+        manifest_path: AbsolutePathBuf,
+        manifest: PluginManifest<AbsolutePathBuf>,
+    ) -> Result<Self, ResolvedPluginError> {
+        let manifest_path = environment_resource(&environment_id, &root, manifest_path)?;
+        let manifest = manifest
+            .try_map_resources(|path| environment_resource(&environment_id, &root, path))?;
+        Ok(Self {
+            selected_root_id,
+            location: ResolvedPluginLocation::Environment {
+                environment_id,
+                root,
+            },
+            manifest_path,
+            manifest,
+        })
+    }
+
+    /// Returns the opaque ID supplied for the selected capability root.
+    pub fn selected_root_id(&self) -> &str {
+        &self.selected_root_id
+    }
+
+    /// Returns the authority-bound package location.
+    pub fn location(&self) -> &ResolvedPluginLocation {
+        &self.location
+    }
+
+    /// Returns the manifest resource used to resolve this package.
+    pub fn manifest_path(&self) -> &PluginResourceLocator {
+        &self.manifest_path
+    }
+
+    /// Returns package metadata whose resource fields retain their source authority.
+    pub fn manifest(&self) -> &PluginManifest<PluginResourceLocator> {
+        &self.manifest
+    }
+}
+
+fn environment_resource(
+    environment_id: &str,
+    root: &AbsolutePathBuf,
+    path: AbsolutePathBuf,
+) -> Result<PluginResourceLocator, ResolvedPluginError> {
+    if !path.as_path().starts_with(root.as_path()) {
+        return Err(ResolvedPluginError::ResourceOutsideRoot {
+            root: root.clone(),
+            path,
+        });
+    }
+    Ok(PluginResourceLocator::Environment {
+        environment_id: environment_id.to_string(),
+        path,
+    })
+}
+
+/// Resolves source-owned package roots into inert plugin descriptors.
+///
+/// Implementations must perform all filesystem access through the authority
+/// named by the selected root. `None` means the root contains no plugin
+/// manifest and may be handled as another standalone capability.
+pub trait PluginProvider: Send + Sync {
+    /// Source-specific resolution failure.
+    type Error: StdError + Send + Sync + 'static;
+
+    /// Resolves one selected root without activating any of its components.
+    fn resolve(
+        &self,
+        root: &SelectedCapabilityRoot,
+    ) -> impl Future<Output = Result<Option<ResolvedPlugin>, Self::Error>> + Send;
+}
+
+#[cfg(test)]
+#[path = "provider_tests.rs"]
+mod tests;

codex-rs/plugin/src/provider_tests.rs

@@ -0,0 +1,126 @@
+use super::PluginResourceLocator;
+use super::ResolvedPlugin;
+use super::ResolvedPluginError;
+use crate::manifest::PluginManifest;
+use crate::manifest::PluginManifestHooks;
+use crate::manifest::PluginManifestInterface;
+use crate::manifest::PluginManifestPaths;
+use codex_utils_absolute_path::AbsolutePathBuf;
+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 {
+    PluginResourceLocator::Environment {
+        environment_id: environment_id.to_string(),
+        path,
+    }
+}
+
+#[test]
+fn environment_descriptor_binds_every_manifest_resource() {
+    let root = absolute(std::env::current_dir().expect("cwd").join("plugin-root"));
+    let manifest_path = root.join(".codex-plugin/plugin.json");
+    let skills = root.join("skills");
+    let mcp_servers = root.join(".mcp.json");
+    let apps = root.join(".app.json");
+    let hooks = root.join("hooks/hooks.json");
+    let composer_icon = root.join("assets/composer.svg");
+    let logo = root.join("assets/logo.svg");
+    let screenshot = root.join("assets/screenshot.png");
+    let manifest = PluginManifest {
+        name: "demo".to_string(),
+        version: None,
+        description: None,
+        keywords: Vec::new(),
+        paths: PluginManifestPaths {
+            skills: Some(skills.clone()),
+            mcp_servers: Some(mcp_servers.clone()),
+            apps: Some(apps.clone()),
+            hooks: Some(PluginManifestHooks::Paths(vec![hooks.clone()])),
+        },
+        interface: Some(PluginManifestInterface {
+            composer_icon: Some(composer_icon.clone()),
+            logo: Some(logo.clone()),
+            screenshots: vec![screenshot.clone()],
+            ..PluginManifestInterface::default()
+        }),
+    };
+
+    let plugin = ResolvedPlugin::from_environment(
+        "selected-demo".to_string(),
+        "executor-1".to_string(),
+        root,
+        manifest_path.clone(),
+        manifest,
+    )
+    .expect("valid descriptor");
+
+    assert_eq!(
+        plugin.manifest_path(),
+        &resource("executor-1", manifest_path)
+    );
+    assert_eq!(
+        plugin.manifest(),
+        &PluginManifest {
+            name: "demo".to_string(),
+            version: None,
+            description: None,
+            keywords: Vec::new(),
+            paths: PluginManifestPaths {
+                skills: Some(resource("executor-1", skills)),
+                mcp_servers: Some(resource("executor-1", mcp_servers)),
+                apps: Some(resource("executor-1", apps)),
+                hooks: Some(PluginManifestHooks::Paths(vec![resource(
+                    "executor-1",
+                    hooks,
+                )])),
+            },
+            interface: Some(PluginManifestInterface {
+                composer_icon: Some(resource("executor-1", composer_icon)),
+                logo: Some(resource("executor-1", logo)),
+                screenshots: vec![resource("executor-1", screenshot)],
+                ..PluginManifestInterface::default()
+            }),
+        }
+    );
+}
+
+#[test]
+fn environment_descriptor_rejects_resources_outside_package_root() {
+    let cwd = std::env::current_dir().expect("cwd");
+    let root = absolute(cwd.join("plugin-root"));
+    let outside = absolute(cwd.join("outside/.mcp.json"));
+    let manifest = PluginManifest {
+        name: "demo".to_string(),
+        version: None,
+        description: None,
+        keywords: Vec::new(),
+        paths: PluginManifestPaths {
+            skills: None,
+            mcp_servers: Some(outside.clone()),
+            apps: None,
+            hooks: None,
+        },
+        interface: None,
+    };
+
+    let err = ResolvedPlugin::from_environment(
+        "selected-demo".to_string(),
+        "executor-1".to_string(),
+        root.clone(),
+        root.join(".codex-plugin/plugin.json"),
+        manifest,
+    )
+    .expect_err("outside resource should fail");
+
+    assert_eq!(
+        err,
+        ResolvedPluginError::ResourceOutsideRoot {
+            root,
+            path: outside,
+        }
+    );
+}