codex-tools: extract tool spec models

codex-rs/core/src/client_common.rs

@@ -1,10 +1,10 @@
-use crate::client_common::tools::ToolSpec;
 use crate::config::types::Personality;
 use crate::error::Result;
 pub use codex_api::common::ResponseEvent;
 use codex_protocol::models::BaseInstructions;
 use codex_protocol::models::FunctionCallOutputBody;
 use codex_protocol::models::ResponseItem;
+use codex_tools::ToolSpec;
 use futures::Stream;
 use serde::Deserialize;
 use serde_json::Value;
@@ -157,107 +157,11 @@ fn strip_total_output_header(output: &str) -> Option<(&str, u32)> {
 }
 
 pub(crate) mod tools {
-    use codex_protocol::config_types::WebSearchContextSize;
-    use codex_protocol::config_types::WebSearchFilters as ConfigWebSearchFilters;
-    use codex_protocol::config_types::WebSearchUserLocation as ConfigWebSearchUserLocation;
-    use codex_protocol::config_types::WebSearchUserLocationType;
     pub(crate) use codex_tools::FreeformTool;
     pub(crate) use codex_tools::FreeformToolFormat;
-    use codex_tools::JsonSchema;
     pub(crate) use codex_tools::ResponsesApiTool;
     pub(crate) use codex_tools::ToolSearchOutputTool;
-    use serde::Serialize;
-
-    /// When serialized as JSON, this produces a valid "Tool" in the OpenAI
-    /// Responses API.
-    #[derive(Debug, Clone, Serialize, PartialEq)]
-    #[serde(tag = "type")]
-    pub(crate) enum ToolSpec {
-        #[serde(rename = "function")]
-        Function(ResponsesApiTool),
-        #[serde(rename = "tool_search")]
-        ToolSearch {
-            execution: String,
-            description: String,
-            parameters: JsonSchema,
-        },
-        #[serde(rename = "local_shell")]
-        LocalShell {},
-        #[serde(rename = "image_generation")]
-        ImageGeneration { output_format: String },
-        // TODO: Understand why we get an error on web_search although the API docs say it's supported.
-        // https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses#:~:text=%7B%20type%3A%20%22web_search%22%20%7D%2C
-        // The `external_web_access` field determines whether the web search is over cached or live content.
-        // https://platform.openai.com/docs/guides/tools-web-search#live-internet-access
-        #[serde(rename = "web_search")]
-        WebSearch {
-            #[serde(skip_serializing_if = "Option::is_none")]
-            external_web_access: Option<bool>,
-            #[serde(skip_serializing_if = "Option::is_none")]
-            filters: Option<ResponsesApiWebSearchFilters>,
-            #[serde(skip_serializing_if = "Option::is_none")]
-            user_location: Option<ResponsesApiWebSearchUserLocation>,
-            #[serde(skip_serializing_if = "Option::is_none")]
-            search_context_size: Option<WebSearchContextSize>,
-            #[serde(skip_serializing_if = "Option::is_none")]
-            search_content_types: Option<Vec<String>>,
-        },
-        #[serde(rename = "custom")]
-        Freeform(FreeformTool),
-    }
-
-    impl ToolSpec {
-        pub(crate) fn name(&self) -> &str {
-            match self {
-                ToolSpec::Function(tool) => tool.name.as_str(),
-                ToolSpec::ToolSearch { .. } => "tool_search",
-                ToolSpec::LocalShell {} => "local_shell",
-                ToolSpec::ImageGeneration { .. } => "image_generation",
-                ToolSpec::WebSearch { .. } => "web_search",
-                ToolSpec::Freeform(tool) => tool.name.as_str(),
-            }
-        }
-    }
-
-    #[derive(Debug, Clone, Serialize, PartialEq)]
-    pub(crate) struct ResponsesApiWebSearchFilters {
-        #[serde(skip_serializing_if = "Option::is_none")]
-        pub(crate) allowed_domains: Option<Vec<String>>,
-    }
-
-    impl From<ConfigWebSearchFilters> for ResponsesApiWebSearchFilters {
-        fn from(filters: ConfigWebSearchFilters) -> Self {
-            Self {
-                allowed_domains: filters.allowed_domains,
-            }
-        }
-    }
-
-    #[derive(Debug, Clone, Serialize, PartialEq)]
-    pub(crate) struct ResponsesApiWebSearchUserLocation {
-        #[serde(rename = "type")]
-        pub(crate) r#type: WebSearchUserLocationType,
-        #[serde(skip_serializing_if = "Option::is_none")]
-        pub(crate) country: Option<String>,
-        #[serde(skip_serializing_if = "Option::is_none")]
-        pub(crate) region: Option<String>,
-        #[serde(skip_serializing_if = "Option::is_none")]
-        pub(crate) city: Option<String>,
-        #[serde(skip_serializing_if = "Option::is_none")]
-        pub(crate) timezone: Option<String>,
-    }
-
-    impl From<ConfigWebSearchUserLocation> for ResponsesApiWebSearchUserLocation {
-        fn from(user_location: ConfigWebSearchUserLocation) -> Self {
-            Self {
-                r#type: user_location.r#type,
-                country: user_location.country,
-                region: user_location.region,
-                city: user_location.city,
-                timezone: user_location.timezone,
-            }
-        }
-    }
+    pub(crate) use codex_tools::ToolSpec;
 }
 
 pub struct ResponseStream {

codex-rs/core/src/tools/spec_tests.rs

@@ -1,4 +1,3 @@
-use crate::client_common::tools::FreeformTool;
 use crate::config::test_config;
 use crate::models_manager::manager::ModelsManager;
 use crate::models_manager::model_info::with_config_overrides;
@@ -12,6 +11,9 @@ use codex_protocol::openai_models::InputModality;
 use codex_protocol::openai_models::ModelInfo;
 use codex_protocol::openai_models::ModelsResponse;
 use codex_tools::AdditionalProperties;
+use codex_tools::FreeformTool;
+use codex_tools::ResponsesApiWebSearchFilters;
+use codex_tools::ResponsesApiWebSearchUserLocation;
 use codex_tools::mcp_tool_to_deferred_responses_api_tool;
 use codex_utils_absolute_path::AbsolutePathBuf;
 use pretty_assertions::assert_eq;
@@ -106,14 +108,7 @@ fn deferred_responses_api_tool_serializes_with_defer_loading() {
 }
 
 fn tool_name(tool: &ToolSpec) -> &str {
-    match tool {
-        ToolSpec::Function(ResponsesApiTool { name, .. }) => name,
-        ToolSpec::ToolSearch { .. } => "tool_search",
-        ToolSpec::LocalShell {} => "local_shell",
-        ToolSpec::ImageGeneration { .. } => "image_generation",
-        ToolSpec::WebSearch { .. } => "web_search",
-        ToolSpec::Freeform(FreeformTool { name, .. }) => name,
-    }
+    tool.name()
 }
 
 // Avoid order-based assertions; compare via set containment instead.
@@ -1077,10 +1072,10 @@ fn web_search_config_is_forwarded_to_tool_spec() {
             external_web_access: Some(true),
             filters: web_search_config
                 .filters
-                .map(crate::client_common::tools::ResponsesApiWebSearchFilters::from),
+                .map(ResponsesApiWebSearchFilters::from),
             user_location: web_search_config
                 .user_location
-                .map(crate::client_common::tools::ResponsesApiWebSearchUserLocation::from),
+                .map(ResponsesApiWebSearchUserLocation::from),
             search_context_size: web_search_config.search_context_size,
             search_content_types: None,
         }

codex-rs/tools/README.md

@@ -11,10 +11,13 @@ schema and Responses API tool primitives that no longer need to live in
 - `JsonSchema`
 - `AdditionalProperties`
 - `ToolDefinition`
+- `ToolSpec`
 - `ResponsesApiTool`
 - `FreeformTool`
 - `FreeformToolFormat`
 - `ToolSearchOutputTool`
+- `ResponsesApiWebSearchFilters`
+- `ResponsesApiWebSearchUserLocation`
 - `ResponsesApiNamespace`
 - `ResponsesApiNamespaceTool`
 - `parse_tool_input_schema()`

codex-rs/tools/src/lib.rs

@@ -6,6 +6,7 @@ mod json_schema;
 mod mcp_tool;
 mod responses_api;
 mod tool_definition;
+mod tool_spec;
 
 pub use dynamic_tool::parse_dynamic_tool;
 pub use json_schema::AdditionalProperties;
@@ -24,3 +25,6 @@ pub use responses_api::mcp_tool_to_deferred_responses_api_tool;
 pub use responses_api::mcp_tool_to_responses_api_tool;
 pub use responses_api::tool_definition_to_responses_api_tool;
 pub use tool_definition::ToolDefinition;
+pub use tool_spec::ResponsesApiWebSearchFilters;
+pub use tool_spec::ResponsesApiWebSearchUserLocation;
+pub use tool_spec::ToolSpec;

codex-rs/tools/src/tool_spec.rs

@@ -0,0 +1,105 @@
+use crate::FreeformTool;
+use crate::JsonSchema;
+use crate::ResponsesApiTool;
+use codex_protocol::config_types::WebSearchContextSize;
+use codex_protocol::config_types::WebSearchFilters as ConfigWebSearchFilters;
+use codex_protocol::config_types::WebSearchUserLocation as ConfigWebSearchUserLocation;
+use codex_protocol::config_types::WebSearchUserLocationType;
+use serde::Serialize;
+
+/// When serialized as JSON, this produces a valid "Tool" in the OpenAI
+/// Responses API.
+#[derive(Debug, Clone, Serialize, PartialEq)]
+#[serde(tag = "type")]
+pub enum ToolSpec {
+    #[serde(rename = "function")]
+    Function(ResponsesApiTool),
+    #[serde(rename = "tool_search")]
+    ToolSearch {
+        execution: String,
+        description: String,
+        parameters: JsonSchema,
+    },
+    #[serde(rename = "local_shell")]
+    LocalShell {},
+    #[serde(rename = "image_generation")]
+    ImageGeneration { output_format: String },
+    // TODO: Understand why we get an error on web_search although the API docs
+    // say it's supported.
+    // https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses#:~:text=%7B%20type%3A%20%22web_search%22%20%7D%2C
+    // The `external_web_access` field determines whether the web search is over
+    // cached or live content.
+    // https://platform.openai.com/docs/guides/tools-web-search#live-internet-access
+    #[serde(rename = "web_search")]
+    WebSearch {
+        #[serde(skip_serializing_if = "Option::is_none")]
+        external_web_access: Option<bool>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        filters: Option<ResponsesApiWebSearchFilters>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        user_location: Option<ResponsesApiWebSearchUserLocation>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        search_context_size: Option<WebSearchContextSize>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        search_content_types: Option<Vec<String>>,
+    },
+    #[serde(rename = "custom")]
+    Freeform(FreeformTool),
+}
+
+impl ToolSpec {
+    pub fn name(&self) -> &str {
+        match self {
+            ToolSpec::Function(tool) => tool.name.as_str(),
+            ToolSpec::ToolSearch { .. } => "tool_search",
+            ToolSpec::LocalShell {} => "local_shell",
+            ToolSpec::ImageGeneration { .. } => "image_generation",
+            ToolSpec::WebSearch { .. } => "web_search",
+            ToolSpec::Freeform(tool) => tool.name.as_str(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct ResponsesApiWebSearchFilters {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub allowed_domains: Option<Vec<String>>,
+}
+
+impl From<ConfigWebSearchFilters> for ResponsesApiWebSearchFilters {
+    fn from(filters: ConfigWebSearchFilters) -> Self {
+        Self {
+            allowed_domains: filters.allowed_domains,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct ResponsesApiWebSearchUserLocation {
+    #[serde(rename = "type")]
+    pub r#type: WebSearchUserLocationType,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub country: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub region: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub city: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub timezone: Option<String>,
+}
+
+impl From<ConfigWebSearchUserLocation> for ResponsesApiWebSearchUserLocation {
+    fn from(user_location: ConfigWebSearchUserLocation) -> Self {
+        Self {
+            r#type: user_location.r#type,
+            country: user_location.country,
+            region: user_location.region,
+            city: user_location.city,
+            timezone: user_location.timezone,
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "tool_spec_tests.rs"]
+mod tests;

codex-rs/tools/src/tool_spec_tests.rs

@@ -0,0 +1,183 @@
+use super::ResponsesApiWebSearchFilters;
+use super::ResponsesApiWebSearchUserLocation;
+use super::ToolSpec;
+use crate::AdditionalProperties;
+use crate::FreeformTool;
+use crate::FreeformToolFormat;
+use crate::JsonSchema;
+use crate::ResponsesApiTool;
+use codex_protocol::config_types::WebSearchContextSize;
+use codex_protocol::config_types::WebSearchFilters as ConfigWebSearchFilters;
+use codex_protocol::config_types::WebSearchUserLocation as ConfigWebSearchUserLocation;
+use codex_protocol::config_types::WebSearchUserLocationType;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+use std::collections::BTreeMap;
+
+#[test]
+fn tool_spec_name_covers_all_variants() {
+    assert_eq!(
+        ToolSpec::Function(ResponsesApiTool {
+            name: "lookup_order".to_string(),
+            description: "Look up an order".to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::new(),
+                required: None,
+                additional_properties: None,
+            },
+            output_schema: None,
+        })
+        .name(),
+        "lookup_order"
+    );
+    assert_eq!(
+        ToolSpec::ToolSearch {
+            execution: "sync".to_string(),
+            description: "Search for tools".to_string(),
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::new(),
+                required: None,
+                additional_properties: None,
+            },
+        }
+        .name(),
+        "tool_search"
+    );
+    assert_eq!(ToolSpec::LocalShell {}.name(), "local_shell");
+    assert_eq!(
+        ToolSpec::ImageGeneration {
+            output_format: "png".to_string(),
+        }
+        .name(),
+        "image_generation"
+    );
+    assert_eq!(
+        ToolSpec::WebSearch {
+            external_web_access: Some(true),
+            filters: None,
+            user_location: None,
+            search_context_size: None,
+            search_content_types: None,
+        }
+        .name(),
+        "web_search"
+    );
+    assert_eq!(
+        ToolSpec::Freeform(FreeformTool {
+            name: "exec".to_string(),
+            description: "Run a command".to_string(),
+            format: FreeformToolFormat {
+                r#type: "grammar".to_string(),
+                syntax: "lark".to_string(),
+                definition: "start: \"exec\"".to_string(),
+            },
+        })
+        .name(),
+        "exec"
+    );
+}
+
+#[test]
+fn web_search_config_converts_to_responses_api_types() {
+    assert_eq!(
+        ResponsesApiWebSearchFilters::from(ConfigWebSearchFilters {
+            allowed_domains: Some(vec!["example.com".to_string()]),
+        }),
+        ResponsesApiWebSearchFilters {
+            allowed_domains: Some(vec!["example.com".to_string()]),
+        }
+    );
+    assert_eq!(
+        ResponsesApiWebSearchUserLocation::from(ConfigWebSearchUserLocation {
+            r#type: WebSearchUserLocationType::Approximate,
+            country: Some("US".to_string()),
+            region: Some("California".to_string()),
+            city: Some("San Francisco".to_string()),
+            timezone: Some("America/Los_Angeles".to_string()),
+        }),
+        ResponsesApiWebSearchUserLocation {
+            r#type: WebSearchUserLocationType::Approximate,
+            country: Some("US".to_string()),
+            region: Some("California".to_string()),
+            city: Some("San Francisco".to_string()),
+            timezone: Some("America/Los_Angeles".to_string()),
+        }
+    );
+}
+
+#[test]
+fn web_search_tool_spec_serializes_expected_wire_shape() {
+    assert_eq!(
+        serde_json::to_value(ToolSpec::WebSearch {
+            external_web_access: Some(true),
+            filters: Some(ResponsesApiWebSearchFilters {
+                allowed_domains: Some(vec!["example.com".to_string()]),
+            }),
+            user_location: Some(ResponsesApiWebSearchUserLocation {
+                r#type: WebSearchUserLocationType::Approximate,
+                country: Some("US".to_string()),
+                region: Some("California".to_string()),
+                city: Some("San Francisco".to_string()),
+                timezone: Some("America/Los_Angeles".to_string()),
+            }),
+            search_context_size: Some(WebSearchContextSize::High),
+            search_content_types: Some(vec!["text".to_string(), "image".to_string()]),
+        })
+        .expect("serialize web_search"),
+        json!({
+            "type": "web_search",
+            "external_web_access": true,
+            "filters": {
+                "allowed_domains": ["example.com"],
+            },
+            "user_location": {
+                "type": "approximate",
+                "country": "US",
+                "region": "California",
+                "city": "San Francisco",
+                "timezone": "America/Los_Angeles",
+            },
+            "search_context_size": "high",
+            "search_content_types": ["text", "image"],
+        })
+    );
+}
+
+#[test]
+fn tool_search_tool_spec_serializes_expected_wire_shape() {
+    assert_eq!(
+        serde_json::to_value(ToolSpec::ToolSearch {
+            execution: "sync".to_string(),
+            description: "Search app tools".to_string(),
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::from([(
+                    "query".to_string(),
+                    JsonSchema::String {
+                        description: Some("Tool search query".to_string()),
+                    },
+                )]),
+                required: Some(vec!["query".to_string()]),
+                additional_properties: Some(AdditionalProperties::Boolean(false)),
+            },
+        })
+        .expect("serialize tool_search"),
+        json!({
+            "type": "tool_search",
+            "execution": "sync",
+            "description": "Search app tools",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": "Tool search query",
+                    }
+                },
+                "required": ["query"],
+                "additionalProperties": false,
+            },
+        })
+    );
+}