skills: make backend plugin skills invocable without an executor (#27387)

## Why #27198 made the extension-owned `codex_apps` MCP connection the hosted plugin runtime, but its `mcp/skill` resources still bypassed the skills extension. App-server could list and read those resources through generic MCP APIs, but a thread with no selected environment did not expose them in the model's skills catalog or load their `SKILL.md` through `$skill`. Hosted skills should stay remote while using the same typed catalog, source authority, deduplication, bounded contextual catalog, and selected-skill prompt injection as host and executor skills. They should not be downloaded or exposed as ambient filesystem paths. ## What changed - Add a session-scoped `McpResourceClient` over the replaceable MCP connection manager so resource list/read calls follow startup and refresh replacements. - Add a `BackendSkillProvider` that pages `codex_apps` resources, accepts bounded and validated `mcp/skill` entries, and reads a selected skill's `SKILL.md` through the same MCP connection. - Register the remote provider in app-server and include it in the skills catalog even when a thread has no selected capability roots or executor. - Contribute hosted skill metadata through the bounded `AvailableSkillsInstructions` developer-context path, exclude remote entries from per-turn catalog injection, and classify `<skills>` messages as contextual developer content so rollback can trim and rebuild them correctly. ## Testing - Extend the app-server MCP resource integration test with `environments: []` to exercise two-page discovery, filter a non-`mcp/skill` resource, verify the escaped developer catalog entry and user-role `<skill>` fragment containing the fetched `SKILL.md`, and preserve generic MCP resource reads. - Add core event-mapping coverage that classifies `<skills>` developer messages as contextual history.
2026-07-01 00:31:56 +08:00 · 2026-06-11 10:28:16 +01:00
parent 53b5019745
commit a287c5dffd
26 changed files with 877 additions and 116 deletions
@@ -76,7 +76,10 @@ where
    codex_skills_extension::install_with_providers(
        &mut builder,
        codex_skills_extension::SkillProviders::new()
-            .with_executor_provider(executor_skill_provider),
+            .with_executor_provider(executor_skill_provider)
+            .with_orchestrator_provider(Arc::new(
+                codex_skills_extension::OrchestratorSkillProvider::new(),
+            )),
    );
    Arc::new(builder.build())
 }
@@ -19,6 +19,8 @@ use codex_app_server_protocol::McpResourceReadResponse;
 use codex_app_server_protocol::RequestId;
 use codex_app_server_protocol::ThreadStartParams;
 use codex_app_server_protocol::ThreadStartResponse;
+use codex_app_server_protocol::TurnStartParams;
+use codex_app_server_protocol::UserInput;
 use codex_arg0::Arg0DispatchPaths;
 use codex_config::CloudConfigBundleLoader;
 use codex_config::LoaderOverrides;
@@ -30,9 +32,14 @@ use codex_protocol::protocol::SessionSource;
 use core_test_support::responses;
 use pretty_assertions::assert_eq;
 use rmcp::handler::server::ServerHandler;
+use rmcp::model::ListResourcesResult;
+use rmcp::model::Meta;
+use rmcp::model::PaginatedRequestParams;
 use rmcp::model::ProtocolVersion;
+use rmcp::model::RawResource;
 use rmcp::model::ReadResourceRequestParams;
 use rmcp::model::ReadResourceResult;
+use rmcp::model::Resource;
 use rmcp::model::ResourceContents;
 use rmcp::model::ServerCapabilities;
 use rmcp::model::ServerInfo;
@@ -41,6 +48,7 @@ use rmcp::service::RoleServer;
 use rmcp::transport::StreamableHttpServerConfig;
 use rmcp::transport::StreamableHttpService;
 use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;
+use serde_json::json;
 use tempfile::TempDir;
 use tokio::net::TcpListener;
 use tokio::task::JoinHandle;
@@ -51,49 +59,21 @@ const TEST_RESOURCE_URI: &str = "test://codex/resource";
 const TEST_BLOB_RESOURCE_URI: &str = "test://codex/resource.bin";
 const TEST_RESOURCE_BLOB: &str = "YmluYXJ5LXJlc291cmNl";
 const TEST_RESOURCE_TEXT: &str = "Resource body from the MCP server.";
+const SKILL_NAME: &str = "demo-plugin:deploy";
+const RAW_SKILL_DESCRIPTION: &str = "Deploy\nthrough the <hosted> orchestrator.";
+const SKILL_DESCRIPTION: &str = "Deploy through the &lt;hosted&gt; orchestrator.";
+const SKILL_RESOURCE_URI: &str = "skill://plugin_demo/deploy";
+const SKILL_MAIN_PROMPT_URI: &str = "skill://plugin_demo/deploy/SKILL.md";
+const SKILL_MARKER: &str = "ORCHESTRATOR_SKILL_BODY_MARKER";
+const SKILL_CONTENTS: &str = "---\nname: deploy\ndescription: Deploy through the orchestrator.\n---\n\n# Deploy\n\nORCHESTRATOR_SKILL_BODY_MARKER\n";

 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn mcp_resource_read_returns_resource_contents() -> Result<()> {
    let responses_server = responses::start_mock_server().await;
    let (apps_server_url, apps_server_handle) = start_resource_apps_mcp_server().await?;
-
-    let codex_home = TempDir::new()?;
    let responses_server_uri = responses_server.uri();
-    std::fs::write(
-        codex_home.path().join("config.toml"),
-        format!(
-            r#"
-model = "mock-model"
-approval_policy = "untrusted"
-sandbox_mode = "read-only"
-
-model_provider = "mock_provider"
-chatgpt_base_url = "{apps_server_url}"
-mcp_oauth_credentials_store = "file"
-
-[features]
-apps = true
-
-[model_providers.mock_provider]
-name = "Mock provider for test"
-base_url = "{responses_server_uri}/v1"
-wire_api = "responses"
-request_max_retries = 0
-stream_max_retries = 0
-"#
-        ),
-    )?;
-    write_chatgpt_auth(
-        codex_home.path(),
-        ChatGptAuthFixture::new("chatgpt-token")
-            .account_id("account-123")
-            .chatgpt_user_id("user-123")
-            .chatgpt_account_id("account-123"),
-        AuthCredentialsStoreMode::File,
-    )?;
-
-    let mut mcp = TestAppServer::new(codex_home.path()).await?;
-    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+    let (_codex_home, mut mcp) =
+        start_resource_test_app_server(&apps_server_url, &responses_server_uri).await?;

    let thread_start_id = mcp
        .send_thread_start_request(ThreadStartParams {
@@ -120,7 +100,6 @@ stream_max_retries = 0
        mcp.read_stream_until_response_message(RequestId::Integer(read_request_id)),
    )
    .await??;
-
    assert_eq!(
        to_response::<McpResourceReadResponse>(read_response)?,
        expected_resource_read_response()
@@ -131,6 +110,87 @@ stream_max_retries = 0
    Ok(())
 }

+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn codex_apps_resources_support_orchestrator_skills_without_an_environment() -> Result<()> {
+    let responses_server = responses::start_mock_server().await;
+    let (apps_server_url, apps_server_handle) = start_resource_apps_mcp_server().await?;
+    let responses_server_uri = responses_server.uri();
+    let (_codex_home, mut mcp) =
+        start_resource_test_app_server(&apps_server_url, &responses_server_uri).await?;
+
+    let thread_start_id = mcp
+        .send_thread_start_request(ThreadStartParams {
+            model: Some("mock-model".to_string()),
+            environments: Some(Vec::new()),
+            ..Default::default()
+        })
+        .await?;
+    let thread_start_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(thread_start_id)),
+    )
+    .await??;
+    let ThreadStartResponse { thread, .. } = to_response(thread_start_resp)?;
+
+    let response_mock = responses::mount_sse_once(
+        &responses_server,
+        responses::sse(vec![
+            responses::ev_response_created("resp-orchestrator-skill"),
+            responses::ev_assistant_message("msg-orchestrator-skill", "Done"),
+            responses::ev_completed("resp-orchestrator-skill"),
+        ]),
+    )
+    .await;
+    let turn_start_id = mcp
+        .send_turn_start_request(TurnStartParams {
+            thread_id: thread.id,
+            input: vec![UserInput::Text {
+                text: format!("Use ${SKILL_NAME}"),
+                text_elements: Vec::new(),
+            }],
+            ..Default::default()
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(turn_start_id)),
+    )
+    .await??;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("turn/completed"),
+    )
+    .await??;
+
+    let request = response_mock.single_request();
+    let developer_messages = request.message_input_texts("developer");
+    let catalog_line = format!("- {SKILL_NAME}: {SKILL_DESCRIPTION} (file: {SKILL_RESOURCE_URI})");
+    assert_eq!(
+        1,
+        developer_messages
+            .iter()
+            .filter(|text| text.contains(&catalog_line))
+            .count()
+    );
+    assert!(
+        developer_messages
+            .iter()
+            .all(|text| !text.contains("ignored-plugin:ignored"))
+    );
+    let skill_fragments = request
+        .message_input_texts("user")
+        .into_iter()
+        .filter(|text| text.starts_with("<skill>"))
+        .collect::<Vec<_>>();
+    assert_eq!(1, skill_fragments.len());
+    assert!(skill_fragments[0].contains(&format!("<name>{SKILL_NAME}</name>")));
+    assert!(skill_fragments[0].contains(SKILL_MARKER));
+
+    apps_server_handle.abort();
+    let _ = apps_server_handle.await;
+    Ok(())
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn mcp_resource_read_returns_resource_contents_without_thread() -> Result<()> {
    let (apps_server_url, apps_server_handle) = start_resource_apps_mcp_server().await?;
@@ -246,6 +306,52 @@ async fn mcp_resource_read_returns_error_for_unknown_thread() -> Result<()> {
    Ok(())
 }

+async fn start_resource_test_app_server(
+    apps_server_url: &str,
+    responses_server_uri: &str,
+) -> Result<(TempDir, TestAppServer)> {
+    let codex_home = TempDir::new()?;
+    std::fs::write(
+        codex_home.path().join("config.toml"),
+        format!(
+            r#"
+model = "mock-model"
+approval_policy = "untrusted"
+sandbox_mode = "read-only"
+
+model_provider = "mock_provider"
+chatgpt_base_url = "{apps_server_url}"
+mcp_oauth_credentials_store = "file"
+
+[features]
+apps = true
+
+[skills]
+include_instructions = true
+
+[model_providers.mock_provider]
+name = "Mock provider for test"
+base_url = "{responses_server_uri}/v1"
+wire_api = "responses"
+request_max_retries = 0
+stream_max_retries = 0
+"#
+        ),
+    )?;
+    write_chatgpt_auth(
+        codex_home.path(),
+        ChatGptAuthFixture::new("chatgpt-token")
+            .account_id("account-123")
+            .chatgpt_user_id("user-123")
+            .chatgpt_account_id("account-123"),
+        AuthCredentialsStoreMode::File,
+    )?;
+
+    let mut mcp = TestAppServer::new(codex_home.path()).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+    Ok((codex_home, mcp))
+}
+
 async fn start_resource_apps_mcp_server() -> Result<(String, JoinHandle<()>)> {
    let listener = TcpListener::bind("127.0.0.1:0").await?;
    let addr = listener.local_addr()?;
@@ -292,12 +398,69 @@ impl ServerHandler for ResourceAppsMcpServer {
            .with_protocol_version(ProtocolVersion::V_2025_06_18)
    }

+    async fn list_resources(
+        &self,
+        request: Option<PaginatedRequestParams>,
+        _context: RequestContext<RoleServer>,
+    ) -> Result<ListResourcesResult, rmcp::ErrorData> {
+        let cursor = request.and_then(|request| request.cursor);
+        if cursor.is_none() {
+            return Ok(ListResourcesResult {
+                resources: vec![skill_resource(
+                    "skill://plugin_ignored/ignored",
+                    "plugin_ignored/ignored",
+                    "Not an MCP skill resource.",
+                    "text/plain",
+                    "ignored-plugin",
+                    "ignored",
+                )],
+                next_cursor: Some("skills-page".to_string()),
+                meta: None,
+            });
+        }
+        if cursor.as_deref() == Some("failing-page") {
+            return Err(rmcp::ErrorData::internal_error(
+                "simulated later-page failure",
+                /*data*/ None,
+            ));
+        }
+        if cursor.as_deref() != Some("skills-page") {
+            return Err(rmcp::ErrorData::invalid_params(
+                "unexpected resources/list cursor",
+                /*data*/ None,
+            ));
+        }
+
+        Ok(ListResourcesResult {
+            resources: vec![skill_resource(
+                SKILL_RESOURCE_URI,
+                "plugin_demo/deploy",
+                RAW_SKILL_DESCRIPTION,
+                "mcp/skill",
+                "demo-plugin",
+                "deploy",
+            )],
+            next_cursor: Some("failing-page".to_string()),
+            meta: None,
+        })
+    }
+
    async fn read_resource(
        &self,
        request: ReadResourceRequestParams,
        _context: RequestContext<RoleServer>,
    ) -> Result<ReadResourceResult, rmcp::ErrorData> {
        let uri = request.uri;
+        if uri == SKILL_MAIN_PROMPT_URI {
+            return Ok(ReadResourceResult::new(vec![
+                ResourceContents::TextResourceContents {
+                    uri: SKILL_MAIN_PROMPT_URI.to_string(),
+                    mime_type: Some("text/markdown".to_string()),
+                    text: SKILL_CONTENTS.to_string(),
+                    meta: None,
+                },
+            ]));
+        }
        if uri != TEST_RESOURCE_URI {
            return Err(rmcp::ErrorData::resource_not_found(
                format!("resource not found: {uri}"),
@@ -321,3 +484,27 @@ impl ServerHandler for ResourceAppsMcpServer {
        ]))
    }
 }
+
+fn skill_resource(
+    uri: &str,
+    name: &str,
+    description: &str,
+    mime_type: &str,
+    plugin_name: &str,
+    skill_name: &str,
+) -> Resource {
+    Resource::new(
+        RawResource::new(uri, name)
+            .with_description(description)
+            .with_mime_type(mime_type)
+            .with_meta(skill_resource_meta(plugin_name, skill_name)),
+        /*annotations*/ None,
+    )
+}
+
+fn skill_resource_meta(plugin_name: &str, skill_name: &str) -> Meta {
+    Meta(serde_json::Map::from_iter([
+        ("plugin_name".to_string(), json!(plugin_name)),
+        ("skill_name".to_string(), json!(skill_name)),
+    ]))
+}