mirror of
https://github.com/pchuan98/codex.git
synced 2026-07-01 00:31:56 +08:00
codex-tools: extract responses API tool models (#16031)
## Why The previous extraction steps moved shared tool-schema parsing into `codex-tools`, but `codex-core` still owned the generic Responses API tool models and the last adapter layer that turned parsed tool definitions into `ResponsesApiTool` values. That left `core/src/tools/spec.rs` and `core/src/client_common.rs` holding a chunk of tool-shaping code that does not need session state, runtime plumbing, or any other `codex-core`-specific dependency. As a result, `codex-tools` owned the parsed tool definition, but `codex-core` still owned the generic wire model that those definitions are converted into. This change moves that boundary one step further. `codex-tools` now owns the reusable Responses/tool wire structs and the shared conversion helpers for dynamic tools, MCP tools, and deferred MCP aliases. `codex-core` continues to own `ToolSpec` orchestration and the remaining web-search-specific request shapes. ## What changed - added `tools/src/responses_api.rs` to own `ResponsesApiTool`, `FreeformTool`, `ToolSearchOutputTool`, namespace output types, and the shared `ToolDefinition -> ResponsesApiTool` adapter helpers - added `tools/src/responses_api_tests.rs` for deferred-loading behavior, adapter coverage, and namespace serialization coverage - rewired `core/src/tools/spec.rs` to use the extracted dynamic/MCP adapter helpers instead of defining those conversions locally - rewired `core/src/tools/handlers/tool_search.rs` to use the extracted deferred MCP adapter and namespace output types directly - slimmed `core/src/client_common.rs` so it now keeps `ToolSpec` and the web-search-specific wire types, while reusing the extracted tool models from `codex-tools` - moved the extracted seam tests out of `core` and updated `codex-rs/tools/README.md` plus `tools/src/lib.rs` to reflect the expanded `codex-tools` boundary ## Test plan - `cargo test -p codex-tools` - `cargo test -p codex-core --lib tools::spec::` - `cargo test -p codex-core --lib tools::handlers::tool_search::` - `just fix -p codex-tools -p codex-core` - `just argument-comment-lint` ## References - [#15923](https://github.com/openai/codex/pull/15923) `codex-tools: extract shared tool schema parsing` - [#15928](https://github.com/openai/codex/pull/15928) `codex-tools: extract MCP schema adapters` - [#15944](https://github.com/openai/codex/pull/15944) `codex-tools: extract dynamic tool adapters` - [#15953](https://github.com/openai/codex/pull/15953) `codex-tools: introduce named tool definitions`
This commit is contained in:
Michael Bolin
@@ -1,8 +1,10 @@
|
||||
//! Shared tool-schema parsing primitives that can live outside `codex-core`.
|
||||
//! Shared tool definitions and Responses API tool primitives that can live
|
||||
//! outside `codex-core`.
|
||||
|
||||
mod dynamic_tool;
|
||||
mod json_schema;
|
||||
mod mcp_tool;
|
||||
mod responses_api;
|
||||
mod tool_definition;
|
||||
|
||||
pub use dynamic_tool::parse_dynamic_tool;
|
||||
@@ -11,4 +13,14 @@ pub use json_schema::JsonSchema;
|
||||
pub use json_schema::parse_tool_input_schema;
|
||||
pub use mcp_tool::mcp_call_tool_result_output_schema;
|
||||
pub use mcp_tool::parse_mcp_tool;
|
||||
pub use responses_api::FreeformTool;
|
||||
pub use responses_api::FreeformToolFormat;
|
||||
pub use responses_api::ResponsesApiNamespace;
|
||||
pub use responses_api::ResponsesApiNamespaceTool;
|
||||
pub use responses_api::ResponsesApiTool;
|
||||
pub use responses_api::ToolSearchOutputTool;
|
||||
pub use responses_api::dynamic_tool_to_responses_api_tool;
|
||||
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;
|
||||
|
||||
@@ -0,0 +1,102 @@
|
||||
use crate::JsonSchema;
|
||||
use crate::ToolDefinition;
|
||||
use crate::parse_dynamic_tool;
|
||||
use crate::parse_mcp_tool;
|
||||
use codex_protocol::dynamic_tools::DynamicToolSpec;
|
||||
use serde::Deserialize;
|
||||
use serde::Serialize;
|
||||
use serde_json::Value;
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
|
||||
pub struct FreeformTool {
|
||||
pub name: String,
|
||||
pub description: String,
|
||||
pub format: FreeformToolFormat,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
|
||||
pub struct FreeformToolFormat {
|
||||
pub r#type: String,
|
||||
pub syntax: String,
|
||||
pub definition: String,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, PartialEq)]
|
||||
pub struct ResponsesApiTool {
|
||||
pub name: String,
|
||||
pub description: String,
|
||||
/// TODO: Validation. When strict is set to true, the JSON schema,
|
||||
/// `required` and `additional_properties` must be present. All fields in
|
||||
/// `properties` must be present in `required`.
|
||||
pub strict: bool,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub defer_loading: Option<bool>,
|
||||
pub parameters: JsonSchema,
|
||||
#[serde(skip)]
|
||||
pub output_schema: Option<Value>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, PartialEq)]
|
||||
#[serde(tag = "type")]
|
||||
pub enum ToolSearchOutputTool {
|
||||
#[allow(dead_code)]
|
||||
#[serde(rename = "function")]
|
||||
Function(ResponsesApiTool),
|
||||
#[serde(rename = "namespace")]
|
||||
Namespace(ResponsesApiNamespace),
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, PartialEq)]
|
||||
pub struct ResponsesApiNamespace {
|
||||
pub name: String,
|
||||
pub description: String,
|
||||
pub tools: Vec<ResponsesApiNamespaceTool>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, PartialEq)]
|
||||
#[serde(tag = "type")]
|
||||
pub enum ResponsesApiNamespaceTool {
|
||||
#[serde(rename = "function")]
|
||||
Function(ResponsesApiTool),
|
||||
}
|
||||
|
||||
pub fn dynamic_tool_to_responses_api_tool(
|
||||
tool: &DynamicToolSpec,
|
||||
) -> Result<ResponsesApiTool, serde_json::Error> {
|
||||
Ok(tool_definition_to_responses_api_tool(parse_dynamic_tool(
|
||||
tool,
|
||||
)?))
|
||||
}
|
||||
|
||||
pub fn mcp_tool_to_responses_api_tool(
|
||||
name: String,
|
||||
tool: &rmcp::model::Tool,
|
||||
) -> Result<ResponsesApiTool, serde_json::Error> {
|
||||
Ok(tool_definition_to_responses_api_tool(
|
||||
parse_mcp_tool(tool)?.renamed(name),
|
||||
))
|
||||
}
|
||||
|
||||
pub fn mcp_tool_to_deferred_responses_api_tool(
|
||||
name: String,
|
||||
tool: &rmcp::model::Tool,
|
||||
) -> Result<ResponsesApiTool, serde_json::Error> {
|
||||
Ok(tool_definition_to_responses_api_tool(
|
||||
parse_mcp_tool(tool)?.renamed(name).into_deferred(),
|
||||
))
|
||||
}
|
||||
|
||||
pub fn tool_definition_to_responses_api_tool(tool_definition: ToolDefinition) -> ResponsesApiTool {
|
||||
ResponsesApiTool {
|
||||
name: tool_definition.name,
|
||||
description: tool_definition.description,
|
||||
strict: false,
|
||||
defer_loading: tool_definition.defer_loading.then_some(true),
|
||||
parameters: tool_definition.input_schema,
|
||||
output_schema: tool_definition.output_schema,
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
#[path = "responses_api_tests.rs"]
|
||||
mod tests;
|
||||
@@ -0,0 +1,173 @@
|
||||
use super::ResponsesApiNamespace;
|
||||
use super::ResponsesApiNamespaceTool;
|
||||
use super::ResponsesApiTool;
|
||||
use super::ToolSearchOutputTool;
|
||||
use super::dynamic_tool_to_responses_api_tool;
|
||||
use super::mcp_tool_to_deferred_responses_api_tool;
|
||||
use super::tool_definition_to_responses_api_tool;
|
||||
use crate::JsonSchema;
|
||||
use crate::ToolDefinition;
|
||||
use codex_protocol::dynamic_tools::DynamicToolSpec;
|
||||
use pretty_assertions::assert_eq;
|
||||
use serde_json::json;
|
||||
use std::collections::BTreeMap;
|
||||
|
||||
#[test]
|
||||
fn tool_definition_to_responses_api_tool_omits_false_defer_loading() {
|
||||
assert_eq!(
|
||||
tool_definition_to_responses_api_tool(ToolDefinition {
|
||||
name: "lookup_order".to_string(),
|
||||
description: "Look up an order".to_string(),
|
||||
input_schema: JsonSchema::Object {
|
||||
properties: BTreeMap::from([(
|
||||
"order_id".to_string(),
|
||||
JsonSchema::String { description: None },
|
||||
)]),
|
||||
required: Some(vec!["order_id".to_string()]),
|
||||
additional_properties: Some(false.into()),
|
||||
},
|
||||
output_schema: Some(json!({"type": "object"})),
|
||||
defer_loading: false,
|
||||
}),
|
||||
ResponsesApiTool {
|
||||
name: "lookup_order".to_string(),
|
||||
description: "Look up an order".to_string(),
|
||||
strict: false,
|
||||
defer_loading: None,
|
||||
parameters: JsonSchema::Object {
|
||||
properties: BTreeMap::from([(
|
||||
"order_id".to_string(),
|
||||
JsonSchema::String { description: None },
|
||||
)]),
|
||||
required: Some(vec!["order_id".to_string()]),
|
||||
additional_properties: Some(false.into()),
|
||||
},
|
||||
output_schema: Some(json!({"type": "object"})),
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn dynamic_tool_to_responses_api_tool_preserves_defer_loading() {
|
||||
let tool = DynamicToolSpec {
|
||||
name: "lookup_order".to_string(),
|
||||
description: "Look up an order".to_string(),
|
||||
input_schema: json!({
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"order_id": {"type": "string"}
|
||||
},
|
||||
"required": ["order_id"],
|
||||
"additionalProperties": false,
|
||||
}),
|
||||
defer_loading: true,
|
||||
};
|
||||
|
||||
assert_eq!(
|
||||
dynamic_tool_to_responses_api_tool(&tool).expect("convert dynamic tool"),
|
||||
ResponsesApiTool {
|
||||
name: "lookup_order".to_string(),
|
||||
description: "Look up an order".to_string(),
|
||||
strict: false,
|
||||
defer_loading: Some(true),
|
||||
parameters: JsonSchema::Object {
|
||||
properties: BTreeMap::from([(
|
||||
"order_id".to_string(),
|
||||
JsonSchema::String { description: None },
|
||||
)]),
|
||||
required: Some(vec!["order_id".to_string()]),
|
||||
additional_properties: Some(false.into()),
|
||||
},
|
||||
output_schema: None,
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn mcp_tool_to_deferred_responses_api_tool_sets_defer_loading() {
|
||||
let tool = rmcp::model::Tool {
|
||||
name: "lookup_order".to_string().into(),
|
||||
title: None,
|
||||
description: Some("Look up an order".to_string().into()),
|
||||
input_schema: std::sync::Arc::new(rmcp::model::object(json!({
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"order_id": {"type": "string"}
|
||||
},
|
||||
"required": ["order_id"],
|
||||
"additionalProperties": false,
|
||||
}))),
|
||||
output_schema: None,
|
||||
annotations: None,
|
||||
execution: None,
|
||||
icons: None,
|
||||
meta: None,
|
||||
};
|
||||
|
||||
assert_eq!(
|
||||
mcp_tool_to_deferred_responses_api_tool(
|
||||
"mcp__codex_apps__lookup_order".to_string(),
|
||||
&tool,
|
||||
)
|
||||
.expect("convert deferred tool"),
|
||||
ResponsesApiTool {
|
||||
name: "mcp__codex_apps__lookup_order".to_string(),
|
||||
description: "Look up an order".to_string(),
|
||||
strict: false,
|
||||
defer_loading: Some(true),
|
||||
parameters: JsonSchema::Object {
|
||||
properties: BTreeMap::from([(
|
||||
"order_id".to_string(),
|
||||
JsonSchema::String { description: None },
|
||||
)]),
|
||||
required: Some(vec!["order_id".to_string()]),
|
||||
additional_properties: Some(false.into()),
|
||||
},
|
||||
output_schema: None,
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn tool_search_output_namespace_serializes_with_deferred_child_tools() {
|
||||
let namespace = ToolSearchOutputTool::Namespace(ResponsesApiNamespace {
|
||||
name: "mcp__codex_apps__calendar".to_string(),
|
||||
description: "Plan events".to_string(),
|
||||
tools: vec![ResponsesApiNamespaceTool::Function(ResponsesApiTool {
|
||||
name: "create_event".to_string(),
|
||||
description: "Create a calendar event.".to_string(),
|
||||
strict: false,
|
||||
defer_loading: Some(true),
|
||||
parameters: JsonSchema::Object {
|
||||
properties: Default::default(),
|
||||
required: None,
|
||||
additional_properties: None,
|
||||
},
|
||||
output_schema: None,
|
||||
})],
|
||||
});
|
||||
|
||||
let value = serde_json::to_value(namespace).expect("serialize namespace");
|
||||
|
||||
assert_eq!(
|
||||
value,
|
||||
json!({
|
||||
"type": "namespace",
|
||||
"name": "mcp__codex_apps__calendar",
|
||||
"description": "Plan events",
|
||||
"tools": [
|
||||
{
|
||||
"type": "function",
|
||||
"name": "create_event",
|
||||
"description": "Create a calendar event.",
|
||||
"strict": false,
|
||||
"defer_loading": true,
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {}
|
||||
}
|
||||
}
|
||||
]
|
||||
})
|
||||
);
|
||||
}
|
||||
Reference in New Issue
Block a user