Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Honor catalog schemas for asynchronous user input (#47773)

rhan-oai29f056c26c09
diff --git a/codex-rs/core/src/tools/handlers/request_user_input_async.rs b/codex-rs/core/src/tools/handlers/request_user_input_async.rs
index 2c4c7067ed..da153dcd59 100644
--- a/codex-rs/core/src/tools/handlers/request_user_input_async.rs
+++ b/codex-rs/core/src/tools/handlers/request_user_input_async.rs
@@ -23,6 +23,7 @@ const TOOL_NAME: &str = "request_user_input_async";
pub struct RequestUserInputAsyncHandler {
pub description: String,
+ pub parameters: Option<String>,
}
#[derive(Debug, Deserialize)]
@@ -59,17 +60,28 @@ impl ToolExecutor<ToolInvocation> for RequestUserInputAsyncHandler {
);
questions.min_items = Some(1);
let properties = BTreeMap::from([("questions".to_string(), questions)]);
+ let mut parameters = JsonSchema::object(
+ properties,
+ Some(vec!["questions".to_string()]),
+ /*additional_properties*/ Some(false.into()),
+ );
+ if let Some(parameters_override) = &self.parameters {
+ match crate::tools::catalog_parameters::parse(parameters_override) {
+ Ok(schema) => parameters = schema,
+ Err(reason) => tracing::warn!(
+ tool = TOOL_NAME,
+ reason,
+ "Invalid catalog tool parameters; using bundled parameters"
+ ),
+ }
+ }
ToolSpec::Function(ResponsesApiTool {
name: TOOL_NAME.to_string(),
description: self.description.clone(),
strict: false,
defer_loading: None,
- parameters: JsonSchema::object(
- properties,
- Some(vec!["questions".to_string()]),
- /*additional_properties*/ Some(false.into()),
- ),
+ parameters,
output_schema: None,
})
}
diff --git a/codex-rs/core/src/tools/spec_plan.rs b/codex-rs/core/src/tools/spec_plan.rs
index 738560ca71..f6c3243e4f 100644
--- a/codex-rs/core/src/tools/spec_plan.rs
+++ b/codex-rs/core/src/tools/spec_plan.rs
@@ -1180,11 +1180,15 @@ fn add_core_utility_tools(context: &CoreToolPlanContext<'_>, registry: &mut Tool
)
})
{
+ let model_messages = ResolvedModelMessages::from_model(context.model_info);
registry.add_with_exposure(
RequestUserInputAsyncHandler {
- description: ResolvedModelMessages::from_model(context.model_info)
+ description: model_messages
.request_user_input_async_description()
.to_string(),
+ parameters: model_messages
+ .request_user_input_async_parameters_override()
+ .map(str::to_owned),
},
ToolExposure::DirectModelOnly,
);
diff --git a/codex-rs/core/tests/suite/request_user_input_async.rs b/codex-rs/core/tests/suite/request_user_input_async.rs
index 7ffb260371..9dfcc6b749 100644
--- a/codex-rs/core/tests/suite/request_user_input_async.rs
+++ b/codex-rs/core/tests/suite/request_user_input_async.rs
@@ -342,16 +342,41 @@ async fn freeform_async_message_emits_an_item_without_ending_the_turn(
Ok(())
}
-#[test_case(None, "send_user_message_async"; "fallback_description")]
-#[test_case(None, "request_user_input_async"; "current_catalog_name")]
-#[test_case(Some(ToolMessages::default()), "send_user_message_async"; "missing_tool")]
-#[test_case(Some(ToolMessages { send_user_message_async: Some(ToolMessage::default()), ..Default::default() }), "send_user_message_async"; "missing_description")]
-#[test_case(Some(ToolMessages { send_user_message_async: Some(ToolMessage { description: Some("Catalog async message description.".to_string()), ..Default::default() }), ..Default::default() }), "send_user_message_async"; "catalog_description")]
-#[test_case(Some(ToolMessages { send_user_message_async: Some(ToolMessage { description: Some(String::new()), ..Default::default() }), ..Default::default() }), "send_user_message_async"; "empty_description")]
+const CATALOG_ASYNC_PARAMETERS: &str = r#"{
+ "type": "object",
+ "properties": {
+ "questions": {
+ "type": "array",
+ "description": "Catalog questions for the user.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "title": {"type": "string"},
+ "options": {"type": "array", "items": {"type": "string"}}
+ },
+ "required": ["title"]
+ }
+ }
+ },
+ "required": ["questions"],
+ "additionalProperties": false
+}"#;
+
+#[test_case(None, "send_user_message_async", None; "fallback_description")]
+#[test_case(None, "request_user_input_async", None; "current_catalog_name")]
+#[test_case(Some(ToolMessages::default()), "send_user_message_async", None; "missing_tool")]
+#[test_case(Some(ToolMessages { send_user_message_async: Some(ToolMessage::default()), ..Default::default() }), "send_user_message_async", None; "missing_description")]
+#[test_case(Some(ToolMessages { send_user_message_async: Some(ToolMessage { description: Some("Catalog async message description.".to_string()), ..Default::default() }), ..Default::default() }), "send_user_message_async", None; "catalog_description")]
+#[test_case(Some(ToolMessages { send_user_message_async: Some(ToolMessage { description: Some(String::new()), ..Default::default() }), ..Default::default() }), "send_user_message_async", None; "empty_description")]
+#[test_case(Some(ToolMessages { send_user_message_async: Some(ToolMessage { parameters: Some(CATALOG_ASYNC_PARAMETERS.to_string()), ..Default::default() }), ..Default::default() }), "send_user_message_async", Some(CATALOG_ASYNC_PARAMETERS); "catalog_parameters")]
+#[test_case(Some(ToolMessages { send_user_message_async: Some(ToolMessage { description: Some("Catalog async message description.".to_string()), parameters: Some(CATALOG_ASYNC_PARAMETERS.to_string()) }), ..Default::default() }), "request_user_input_async", Some(CATALOG_ASYNC_PARAMETERS); "catalog_description_and_parameters")]
+#[test_case(Some(ToolMessages { send_user_message_async: Some(ToolMessage { parameters: Some(String::new()), ..Default::default() }), ..Default::default() }), "send_user_message_async", None; "empty_parameters_fallback")]
+#[test_case(Some(ToolMessages { send_user_message_async: Some(ToolMessage { description: Some("Catalog async message description.".to_string()), parameters: Some(r#"{"type":"object","properties":{"questions":{"type":"unsupported"}}}"#.to_string()) }), ..Default::default() }), "send_user_message_async", None; "invalid_parameters_preserve_description")]
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn request_user_input_async_emits_item_and_does_not_end_the_turn(
tool_messages: Option<ToolMessages>,
catalog_tool_name: &'static str,
+ expected_parameters: Option<&'static str>,
) -> Result<()> {
skip_if_no_network!(Ok(()));
@@ -490,17 +515,24 @@ async fn request_user_input_async_emits_item_and_does_not_end_the_turn(
.expect("the async message tool should be directly visible to the model");
assert_eq!(tool["description"], expected_description);
assert_eq!(tool["strict"], false);
- assert_eq!(tool["parameters"]["required"], json!(["questions"]));
- assert_eq!(tool["parameters"]["additionalProperties"], false);
- let schema = &tool["parameters"]["properties"]["questions"];
- assert_eq!(schema["minItems"], 1);
- assert_eq!(schema["items"]["required"], json!(["title"]));
- assert_eq!(schema["items"]["additionalProperties"], false);
- assert_eq!(schema["items"]["properties"]["options"]["minItems"], 1);
- assert_eq!(
- schema["items"]["properties"]["options"]["items"]["type"],
- "string"
- );
+ if let Some(expected_parameters) = expected_parameters {
+ assert_eq!(
+ tool["parameters"],
+ serde_json::from_str::<serde_json::Value>(expected_parameters)?
+ );
+ } else {
+ assert_eq!(tool["parameters"]["required"], json!(["questions"]));
+ assert_eq!(tool["parameters"]["additionalProperties"], false);
+ let schema = &tool["parameters"]["properties"]["questions"];
+ assert_eq!(schema["minItems"], 1);
+ assert_eq!(schema["items"]["required"], json!(["title"]));
+ assert_eq!(schema["items"]["additionalProperties"], false);
+ assert_eq!(schema["items"]["properties"]["options"]["minItems"], 1);
+ assert_eq!(
+ schema["items"]["properties"]["options"]["items"]["type"],
+ "string"
+ );
+ }
assert!(
tools
.iter()
diff --git a/codex-rs/core/tests/suite/scenarios.rs b/codex-rs/core/tests/suite/scenarios.rs
index 3a8c6a5361..491c72631e 100644
--- a/codex-rs/core/tests/suite/scenarios.rs
+++ b/codex-rs/core/tests/suite/scenarios.rs
@@ -220,6 +220,27 @@ async fn astra_asks_an_async_question_and_receives_the_answer_while_working() ->
skip_if_no_network!(Ok(()));
let question = "Who should receive the launch update?";
+ let parameters = json!({
+ "type": "object",
+ "properties": {
+ "questions": {
+ "type": "array",
+ "description": "Catalog questions to ask while continuing work.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "title": {"type": "string", "description": "Catalog question title."},
+ "options": {"type": "array", "items": {"type": "string"}}
+ },
+ "required": ["title"],
+ "additionalProperties": false
+ }
+ }
+ },
+ "required": ["questions"],
+ "additionalProperties": false
+ });
+ let catalog_parameters = parameters.to_string();
let (release_continuation, continuation_gate) = oneshot::channel();
let mut working_message = ev_assistant_message("working", "I drafted a short launch update.");
working_message["item"]["phase"] = json!("commentary");
@@ -272,6 +293,23 @@ async fn astra_asks_an_async_question_and_receives_the_answer_while_working() ->
.with_auth(CodexAuth::create_dummy_chatgpt_auth_for_testing())
.with_config(move |config| {
configure_scenario_catalog(config);
+ config
+ .model_catalog
+ .as_mut()
+ .expect("scenario model catalog")
+ .models
+ .iter_mut()
+ .find(|model| model.slug == "gpt-6-astra")
+ .expect("Astra model")
+ .model_messages
+ .as_mut()
+ .expect("model messages")
+ .tools
+ .get_or_insert_with(Default::default)
+ .send_user_message_async = Some(ToolMessage {
+ parameters: Some(catalog_parameters),
+ ..Default::default()
+ });
config.model_provider.base_url = Some(base_url);
// The gated mock records raw request bodies for the shared snapshot renderer.
config
@@ -326,12 +364,22 @@ async fn astra_asks_an_async_question_and_receives_the_answer_while_working() ->
.await
.iter()
.map(|body| serde_json::from_slice(body))
- .collect::<serde_json::Result<Vec<_>>>()?;
+ .collect::<serde_json::Result<Vec<serde_json::Value>>>()?;
+ for request in &requests {
+ let tool = request["input"][0]["tools"]
+ .as_array()
+ .expect("Responses Lite tools")
+ .iter()
+ .flat_map(|namespace| namespace["tools"].as_array().into_iter().flatten())
+ .find(|tool| tool["name"] == "request_user_input_async")
+ .expect("the async question tool should be directly visible to the model");
+ assert_eq!(tool["parameters"], parameters);
+ }
let entries = requests.iter().map(SnapshotEntry::body).collect::<Vec<_>>();
insta::assert_snapshot!(
"astra_async_question_and_answer",
context_snapshot::format_context_snapshot(
- "Astra asks who a launch update is for, keeps working, and receives the user's answer in the active turn.",
+ "Astra uses the catalog question schema to ask who a launch update is for, keeps working, and receives the user's answer in the active turn.",
&entries,
&ContextSnapshotOptions::default().rewrite_known_segments(),
)
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_async_question_and_answer.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_async_question_and_answer.snap
index a1c7a2a977..72d9cd49bc 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_async_question_and_answer.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_async_question_and_answer.snap
@@ -1,14 +1,14 @@
---
source: core/tests/suite/scenarios.rs
-assertion_line: 304
-expression: "context_snapshot::format_context_snapshot(\"Astra asks who a launch update is for, keeps working, and receives the user's answer in the active turn.\",\n&entries, &ContextSnapshotOptions::default().rewrite_known_segments(),)"
+assertion_line: 375
+expression: "context_snapshot::format_context_snapshot(\"Astra uses the catalog question schema to ask who a launch update is for, keeps working, and receives the user's answer in the active turn.\",\n&entries, &ContextSnapshotOptions::default().rewrite_known_segments(),)"
---
-Scenario: Astra asks who a launch update is for, keeps working, and receives the user's answer in the active turn.
+Scenario: Astra uses the catalog question schema to ask who a launch update is for, keeps working, and receives the user's answer in the active turn.
## Window 1
-- request 1 (request) --
-00:additional_tools/developer (3; hash=32be5470c6e39932):
- - namespace/functions; hash=e7db0a45c4ec3157
+00:additional_tools/developer (3; hash=9922060cb05f2122):
+ - namespace/functions; hash=f1de44f63c977f3d
- custom/exec
- function/wait
- function/request_user_input
diff --git a/codex-rs/core/tests/suite/step_settings.rs b/codex-rs/core/tests/suite/step_settings.rs
index f12af89853..411cb0a5fe 100644
--- a/codex-rs/core/tests/suite/step_settings.rs
+++ b/codex-rs/core/tests/suite/step_settings.rs
@@ -2266,6 +2266,22 @@ async fn tool_messages_follow_mid_turn_model_changes() -> Result<()> {
"additionalProperties": false,
})
};
+ let async_parameters = |model: &str| {
+ json!({
+ "type": "object",
+ "properties": {"questions": {
+ "type": "array",
+ "description": format!("Questions for {model}."),
+ "items": {
+ "type": "object",
+ "properties": {"title": {"type": "string"}},
+ "required": ["title"],
+ },
+ }},
+ "required": ["questions"],
+ "additionalProperties": false,
+ })
+ };
let server = start_mock_server().await;
let response_mock = mount_sse_sequence(
&server,
@@ -2313,7 +2329,7 @@ async fn tool_messages_follow_mid_turn_model_changes() -> Result<()> {
.tools = Some(ToolMessages {
send_user_message_async: Some(ToolMessage {
description: Some(format!("Async message description for {}.", model.slug)),
- ..Default::default()
+ parameters: Some(async_parameters(&model.slug).to_string()),
}),
multi_agent: Some(MultiAgentToolMessages {
spawn_agent: tool_message("spawn_agent"),
@@ -2381,6 +2397,7 @@ async fn tool_messages_follow_mid_turn_model_changes() -> Result<()> {
json!({
"model": body["model"],
"async_description": tool("request_user_input_async")["description"],
+ "async_parameters": tool("request_user_input_async")["parameters"],
"multi_agent_messages": multi_agent_messages,
"channel_post_description": channel_post["description"].as_str().expect("post description").lines().next(),
"channel_post_required": channel_post["parameters"]["required"],
@@ -2394,6 +2411,7 @@ async fn tool_messages_follow_mid_turn_model_changes() -> Result<()> {
.map(|model| json!({
"model": model,
"async_description": format!("Async message description for {model}."),
+ "async_parameters": async_parameters(model),
"multi_agent_messages": MULTI_AGENT_TOOLS
.map(|name| (name.to_string(), json!({
"description": format!("{name} description for {model}."),
diff --git a/codex-rs/prompts/src/model_messages.rs b/codex-rs/prompts/src/model_messages.rs
index 8e7a3158d8..deb4ed3603 100644
--- a/codex-rs/prompts/src/model_messages.rs
+++ b/codex-rs/prompts/src/model_messages.rs
@@ -155,6 +155,17 @@ impl<'a> ResolvedModelMessages<'a> {
.unwrap_or(REQUEST_USER_INPUT_ASYNC_DESCRIPTION)
}
+ /// Selects the asynchronous user-input schema; parsing belongs to the tool consumer.
+ pub fn request_user_input_async_parameters_override(&self) -> Option<&'a str> {
+ self.catalog_messages?
+ .tools
+ .as_ref()?
+ .send_user_message_async
+ .as_ref()?
+ .parameters
+ .as_deref()
+ }
+
/// Selects a V2 tool's static description by its name, independently of its runtime namespace.
/// Missing text retains the tool's bundled description; an empty string replaces it.
pub fn multi_agent_tool_description_override(&self, tool_name: &str) -> Option<&'a str> {
diff --git a/codex-rs/protocol/src/openai_models.rs b/codex-rs/protocol/src/openai_models.rs
index 68d64fed4c..cb0c9f0a94 100644
--- a/codex-rs/protocol/src/openai_models.rs
+++ b/codex-rs/protocol/src/openai_models.rs
@@ -614,7 +614,7 @@ pub struct ToolMessage {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
/// Complete JSON Schema encoded as a string. Consumed by Multi-Agent V2 tools, Code Mode wait,
- /// and the MCP resource helpers.
+ /// request_user_input_async (the send_user_message_async catalog key), and MCP resource helpers.
/// Uses the harness's supported schema subset; unrecognized keywords are ignored.
/// Missing, null, invalid or unsupported structures, or a root without `type: "object"`
/// retains the harness parameters. Schema semantics must remain API-compatible.