feat(skills): expose bounded search and read tools

codex-rs/ext/skills/Cargo.toml

@@ -19,7 +19,12 @@ codex-core = { workspace = true }
 codex-core-skills = { workspace = true }
 codex-extension-api = { workspace = true }
 codex-protocol = { workspace = true }
+codex-tools = { workspace = true }
+schemars = { workspace = true }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
 
 [dev-dependencies]
+codex-utils-output-truncation = { workspace = true }
 pretty_assertions = { workspace = true }
 tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }

codex-rs/ext/skills/src/extension.rs

@@ -12,8 +12,15 @@ use codex_extension_api::ExtensionEventSink;
 use codex_extension_api::ExtensionRegistryBuilder;
 use codex_extension_api::ThreadLifecycleContributor;
 use codex_extension_api::ThreadStartInput;
+use codex_extension_api::ToolCall;
+use codex_extension_api::ToolContributor;
+use codex_extension_api::ToolExecutor;
+use codex_extension_api::TurnAbortInput;
+use codex_extension_api::TurnErrorInput;
 use codex_extension_api::TurnInputContext;
 use codex_extension_api::TurnInputContributor;
+use codex_extension_api::TurnLifecycleContributor;
+use codex_extension_api::TurnStopInput;
 use codex_protocol::protocol::Event;
 use codex_protocol::protocol::EventMsg;
 use codex_protocol::protocol::WarningEvent;
@@ -32,6 +39,7 @@ use crate::sources::SkillProviders;
 use crate::state::SkillsExtensionConfig;
 use crate::state::SkillsThreadState;
 use crate::state::SkillsTurnState;
+use crate::tools::skill_tools;
 
 #[derive(Clone)]
 struct SkillsExtension {
@@ -67,6 +75,35 @@ impl ConfigContributor<Config> for SkillsExtension {
     }
 }
 
+impl ToolContributor for SkillsExtension {
+    fn tools(
+        &self,
+        _session_store: &ExtensionData,
+        thread_store: &ExtensionData,
+    ) -> Vec<Arc<dyn ToolExecutor<ToolCall>>> {
+        let Some(thread_state) = thread_store.get::<SkillsThreadState>() else {
+            return Vec::new();
+        };
+
+        skill_tools(thread_state)
+    }
+}
+
+#[async_trait::async_trait]
+impl TurnLifecycleContributor for SkillsExtension {
+    async fn on_turn_stop(&self, input: TurnStopInput<'_>) {
+        clear_tool_snapshot(input.thread_store, input.turn_store.level_id());
+    }
+
+    async fn on_turn_abort(&self, input: TurnAbortInput<'_>) {
+        clear_tool_snapshot(input.thread_store, input.turn_store.level_id());
+    }
+
+    async fn on_turn_error(&self, input: TurnErrorInput<'_>) {
+        clear_tool_snapshot(input.thread_store, input.turn_id);
+    }
+}
+
 #[async_trait::async_trait]
 impl TurnInputContributor for SkillsExtension {
     async fn contribute(
@@ -99,10 +136,16 @@ impl TurnInputContributor for SkillsExtension {
             include_bundled_skills: config.bundled_skills_enabled,
             include_remote_skills: true,
         };
-        let catalog = self.providers.list_for_turn(query).await;
+        let (catalog, routes) = self.providers.list_for_turn_with_routes(query).await;
         for warning in &catalog.warnings {
             self.emit_warning(&input.turn_id, warning.clone());
         }
+        thread_state.set_tool_snapshot(
+            input.turn_id.clone(),
+            catalog.clone(),
+            host_loaded_skills.clone(),
+            routes.clone(),
+        );
 
         let selected_entries = collect_explicit_skill_mentions(&input.user_input, &catalog);
         let mut fragments: Vec<Box<dyn ContextualUserFragment + Send>> = Vec::new();
@@ -117,7 +160,7 @@ impl TurnInputContributor for SkillsExtension {
         let mut injected_host_skill_prompts = InjectedHostSkillPrompts::default();
         for entry in &selected_entries {
             match self
-                .read_main_prompt(entry, host_loaded_skills.clone())
+                .read_main_prompt(entry, host_loaded_skills.clone(), &routes)
                 .await
             {
                 Ok(read_result) => {
@@ -169,8 +212,9 @@ impl SkillsExtension {
         &self,
         entry: &SkillCatalogEntry,
         host_loaded_skills: Option<Arc<HostLoadedSkills>>,
+        routes: &crate::sources::SkillProviderRoutes,
     ) -> Result<SkillReadResult, String> {
-        self.providers
+        routes
             .read(SkillReadRequest {
                 authority: entry.authority.clone(),
                 package: entry.id.clone(),
@@ -189,6 +233,12 @@ impl SkillsExtension {
     }
 }
 
+fn clear_tool_snapshot(thread_store: &ExtensionData, turn_id: &str) {
+    if let Some(thread_state) = thread_store.get::<SkillsThreadState>() {
+        thread_state.clear_tool_snapshot(turn_id);
+    }
+}
+
 pub fn install(registry: &mut ExtensionRegistryBuilder<Config>) {
     install_with_providers(
         registry,
@@ -205,6 +255,8 @@ pub fn install_with_providers(
         event_sink: registry.event_sink(),
     });
     registry.thread_lifecycle_contributor(extension.clone());
+    registry.turn_lifecycle_contributor(extension.clone());
     registry.config_contributor(extension.clone());
-    registry.turn_input_contributor(extension);
+    registry.turn_input_contributor(extension.clone());
+    registry.tool_contributor(extension);
 }

codex-rs/ext/skills/src/lib.rs

@@ -5,6 +5,7 @@ mod render;
 mod selection;
 mod sources;
 mod state;
+mod tools;
 
 pub use extension::install;
 pub use extension::install_with_providers;

codex-rs/ext/skills/src/render.rs

@@ -45,7 +45,7 @@ pub(crate) fn available_skills_fragment(catalog: &SkillCatalog) -> Option<Availa
             .short_description
             .as_deref()
             .unwrap_or(entry.description.as_str());
-        let line = render_skill_line(entry.name.as_str(), description, entry.rendered_path());
+        let line = render_skill_line(entry, description);
         let next_chars = total_chars.saturating_add(line.chars().count());
         if next_chars > MAX_AVAILABLE_SKILLS_CHARS {
             omitted = omitted.saturating_add(1);
@@ -70,11 +70,15 @@ pub(crate) fn available_skills_fragment(catalog: &SkillCatalog) -> Option<Availa
     })
 }
 
-fn render_skill_line(name: &str, description: &str, path: &str) -> String {
+fn render_skill_line(entry: &crate::catalog::SkillCatalogEntry, description: &str) -> String {
+    let file = format!("file: {}", entry.rendered_path());
+    let handles = crate::tools::catalog_tool_handles(entry).map_or(file.clone(), |tool_handles| {
+        format!("{file}; {tool_handles}")
+    });
     if description.is_empty() {
-        format!("- {name}: (file: {path})")
+        format!("- {}: ({handles})", entry.name)
     } else {
-        format!("- {name}: {description} (file: {path})")
+        format!("- {}: {description} ({handles})", entry.name)
     }
 }
 

codex-rs/ext/skills/src/sources.rs

@@ -1,7 +1,9 @@
 use std::fmt;
 use std::sync::Arc;
 
+use crate::catalog::SkillAuthority;
 use crate::catalog::SkillCatalog;
+use crate::catalog::SkillPackageId;
 use crate::catalog::SkillProviderError;
 use crate::catalog::SkillReadResult;
 use crate::catalog::SkillSearchResult;
@@ -72,6 +74,84 @@ pub struct SkillProviders {
     sources: Vec<SkillProviderSource>,
 }
 
+#[derive(Clone, Default)]
+pub(crate) struct SkillProviderRoutes {
+    routes: Vec<SkillProviderRoute>,
+}
+
+impl fmt::Debug for SkillProviderRoutes {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("SkillProviderRoutes")
+            .field("route_count", &self.routes.len())
+            .finish()
+    }
+}
+
+#[derive(Clone)]
+struct SkillProviderRoute {
+    authority: SkillAuthority,
+    package: SkillPackageId,
+    provider: Arc<dyn SkillProvider>,
+}
+
+impl SkillProviderRoutes {
+    fn push(
+        &mut self,
+        authority: SkillAuthority,
+        package: SkillPackageId,
+        provider: Arc<dyn SkillProvider>,
+    ) {
+        if self
+            .routes
+            .iter()
+            .any(|route| route.authority == authority && route.package == package)
+        {
+            return;
+        }
+        self.routes.push(SkillProviderRoute {
+            authority,
+            package,
+            provider,
+        });
+    }
+
+    fn provider(
+        &self,
+        authority: &SkillAuthority,
+        package: &SkillPackageId,
+    ) -> Option<Arc<dyn SkillProvider>> {
+        self.routes
+            .iter()
+            .find(|route| &route.authority == authority && &route.package == package)
+            .map(|route| Arc::clone(&route.provider))
+    }
+
+    pub(crate) async fn read(
+        &self,
+        request: SkillReadRequest,
+    ) -> Result<SkillReadResult, SkillProviderError> {
+        let Some(provider) = self.provider(&request.authority, &request.package) else {
+            return Err(SkillProviderError::new(
+                "skill package is not available from the requested authority",
+            ));
+        };
+        provider.read(request).await
+    }
+
+    pub(crate) async fn search(
+        &self,
+        request: SkillSearchRequest,
+    ) -> Result<SkillSearchResult, SkillProviderError> {
+        let Some(provider) = self.provider(&request.authority, &request.package) else {
+            return Err(SkillProviderError::new(
+                "skill package is not available from the requested authority",
+            ));
+        };
+        provider.search(request).await
+    }
+}
+
 impl SkillProviders {
     pub fn new() -> Self {
         Self::default()
@@ -100,47 +180,43 @@ impl SkillProviders {
         self
     }
 
-    pub(crate) async fn list_for_turn(&self, query: SkillListQuery) -> SkillCatalog {
+    pub(crate) async fn list_for_turn_with_routes(
+        &self,
+        query: SkillListQuery,
+    ) -> (SkillCatalog, SkillProviderRoutes) {
         let mut catalog = SkillCatalog::default();
+        let mut routes = SkillProviderRoutes::default();
 
         for source in self
             .sources
             .iter()
             .filter(|source| source.should_list(&query))
         {
-            extend_catalog(
-                &mut catalog,
-                source.provider.list(query.clone()).await,
-                source.label.as_str(),
-            );
-        }
-
-        catalog
-    }
-
-    pub(crate) async fn read(
-        &self,
-        request: SkillReadRequest,
-    ) -> Result<SkillReadResult, SkillProviderError> {
-        let mut last_error = None;
-        for source in self
-            .sources
-            .iter()
-            .filter(|source| source.owns_kind(&request.authority.kind))
-        {
-            match source.provider.read(request.clone()).await {
-                Ok(result) => return Ok(result),
-                Err(err) => last_error = Some(err),
+            match source.provider.list(query.clone()).await {
+                Ok(source_catalog) => {
+                    for entry in source_catalog.entries {
+                        let entry_is_new = !catalog.entries.iter().any(|existing| {
+                            existing.authority == entry.authority && existing.id == entry.id
+                        });
+                        if entry_is_new {
+                            routes.push(
+                                entry.authority.clone(),
+                                entry.id.clone(),
+                                Arc::clone(&source.provider),
+                            );
+                            catalog.push_entry(entry);
+                        }
+                    }
+                    catalog.warnings.extend(source_catalog.warnings);
+                }
+                Err(err) => catalog.warnings.push(format!(
+                    "{} skills unavailable: {}",
+                    source.label, err.message
+                )),
             }
         }
 
-        match last_error {
-            Some(err) => Err(err),
-            None => Err(SkillProviderError::new(format!(
-                "{} skill provider is not configured",
-                request.authority.kind
-            ))),
-        }
+        (catalog, routes)
     }
 
     pub async fn search(
@@ -168,16 +244,3 @@ impl SkillProviders {
         }
     }
 }
-
-fn extend_catalog(
-    catalog: &mut SkillCatalog,
-    result: Result<SkillCatalog, SkillProviderError>,
-    label: &str,
-) {
-    match result {
-        Ok(source_catalog) => catalog.extend(source_catalog),
-        Err(err) => catalog
-            .warnings
-            .push(format!("{label} skills unavailable: {}", err.message)),
-    }
-}