Add structured asynchronous user input requests (#42178)

## What changed

- Replace `send_user_message_async` with `request_user_input_async`, accepting one or more questions with optional suggested answers while allowing the turn to continue.
- Attach structured question metadata to asynchronous agent messages while retaining readable fallback text, and preserve it through app-server events, thread history, and generated schemas.
- Continue enabling the new tool for model catalogs that advertise either the old or new tool name.

## Testing

- Cover tool registration, question validation, emitted items, continued turn execution, history preservation, and backwards-compatible deserialization.

GitOrigin-RevId: ffc49aebde2e854c3c50a122aa52805fec3fc6b3
This commit is contained in:
rka-oai
2026-09-02 02:09:35 +00:00
committed by copyberry
parent b21f2e3081
commit 2c79ee6dac
80 changed files with 1110 additions and 146 deletions
+2 -2
View File
@@ -22,8 +22,8 @@ mod request_permissions;
mod request_plugin_install;
pub(crate) mod request_plugin_install_spec;
mod request_user_input;
mod request_user_input_async;
pub(crate) mod request_user_input_spec;
mod send_user_message_async;
pub(crate) mod shell_spec;
mod sleep;
mod test_sync;
@@ -69,7 +69,7 @@ pub use plan::PlanHandler;
pub use request_permissions::RequestPermissionsHandler;
pub use request_plugin_install::RequestPluginInstallHandler;
pub use request_user_input::RequestUserInputHandler;
pub use send_user_message_async::SendUserMessageAsyncHandler;
pub use request_user_input_async::RequestUserInputAsyncHandler;
pub use sleep::SleepHandler;
pub use test_sync::TestSyncHandler;
pub(crate) use tool_search::ToolSearchHandlerCache;
@@ -0,0 +1,147 @@
use crate::function_tool::FunctionCallError;
use crate::tools::context::FunctionToolOutput;
use crate::tools::context::ToolInvocation;
use crate::tools::context::ToolPayload;
use crate::tools::context::boxed_tool_output;
use crate::tools::handlers::parse_arguments;
use crate::tools::registry::CoreToolRuntime;
use crate::tools::registry::ToolExecutor;
use codex_protocol::items::AgentMessageContent;
use codex_protocol::items::AgentMessageDelivery;
use codex_protocol::items::AgentMessageItem;
use codex_protocol::items::AsyncUserInputQuestion;
use codex_protocol::items::TurnItem;
use codex_protocol::models::MessagePhase;
use codex_tools::JsonSchema;
use codex_tools::ResponsesApiTool;
use codex_tools::ToolName;
use codex_tools::ToolSpec;
use serde::Deserialize;
use std::collections::BTreeMap;
const TOOL_NAME: &str = "request_user_input_async";
pub struct RequestUserInputAsyncHandler {
pub description: Option<String>,
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct RequestUserInputAsyncArgs {
questions: Vec<AsyncUserInputQuestion>,
}
impl ToolExecutor<ToolInvocation> for RequestUserInputAsyncHandler {
fn tool_name(&self) -> ToolName {
ToolName::plain(TOOL_NAME)
}
fn spec(&self) -> ToolSpec {
let mut options = JsonSchema::array(
JsonSchema::string(/*description*/ None),
Some("Suggested answers, in display order. Put the recommended answer first; the first option is preselected by default. The user can select one option or enter a free-text answer. Do not include an Other option or a free-text placeholder; the UI provides free-text input automatically. Omit options for a free-text-only question.".to_string()),
);
options.min_items = Some(1);
let question = JsonSchema::object(
BTreeMap::from([
("title".to_string(), JsonSchema::string(Some("The complete question shown to the user, including any context needed to answer it.".to_string()))),
("options".to_string(), options),
]),
Some(vec!["title".to_string()]),
/*additional_properties*/ Some(false.into()),
);
let mut questions = JsonSchema::array(
question,
Some(
"One or more self-contained questions to present together, in display order."
.to_string(),
),
);
questions.min_items = Some(1);
let properties = BTreeMap::from([("questions".to_string(), questions)]);
ToolSpec::Function(ResponsesApiTool {
name: TOOL_NAME.to_string(),
description: self.description.clone().unwrap_or_else(|| {
"Ask the user one or more questions during ongoing work. Use this tool only to request missing information, preferences, constraints, clarification, or approval. The tool returns immediately without ending the turn or waiting for a reply; any reply arrives asynchronously as a new user message. Keep questions concise, self-contained, and easy to understand, using a level of detail appropriate to the user and task. The UI always allows a free-text answer, including when suggested options are provided. A preselected option is not submitted automatically."
.to_string()
}),
strict: false,
defer_loading: None,
parameters: JsonSchema::object(
properties,
Some(vec!["questions".to_string()]),
/*additional_properties*/ Some(false.into()),
),
output_schema: None,
})
}
fn handle<'a>(&'a self, invocation: ToolInvocation) -> codex_tools::ToolExecutorFuture<'a>
where
ToolInvocation: 'a,
{
Box::pin(async move {
let ToolInvocation {
session,
turn,
call_id,
payload,
..
} = invocation;
let ToolPayload::Function { arguments } = payload else {
return Err(FunctionCallError::RespondToModel(format!(
"{TOOL_NAME} handler received unsupported payload"
)));
};
let args: RequestUserInputAsyncArgs = parse_arguments(&arguments)?;
if args.questions.is_empty() {
return Err(FunctionCallError::RespondToModel(
"questions must not be empty".to_string(),
));
}
let mut messages = Vec::with_capacity(args.questions.len());
for question in &args.questions {
if question.title.trim().is_empty() {
return Err(FunctionCallError::RespondToModel(
"question titles must not be empty".to_string(),
));
}
let mut lines = vec![question.title.clone()];
if let Some(options) = &question.options {
if options.is_empty() || options.iter().any(|option| option.trim().is_empty()) {
return Err(FunctionCallError::RespondToModel(
"options must contain at least one non-empty answer".to_string(),
));
}
lines.extend(options.iter().map(|option| format!("- {option}")));
}
messages.push(lines.join("\n"));
}
let item = TurnItem::AgentMessage(AgentMessageItem {
id: call_id,
content: vec![AgentMessageContent::Text {
text: messages.join("\n\n"),
}],
phase: Some(MessagePhase::FinalAnswer),
memory_citation: None,
delivery: Some(AgentMessageDelivery::Async),
questions: Some(args.questions),
});
session.emit_turn_item_started(turn.as_ref(), &item).await;
session.emit_turn_item_completed(turn.as_ref(), item).await;
Ok(boxed_tool_output(FunctionToolOutput::from_text(
r#"{"accepted":true}"#.to_string(),
/*success*/ Some(true),
)))
})
}
}
impl CoreToolRuntime for RequestUserInputAsyncHandler {
fn is_builtin_control_tool(&self) -> bool {
true
}
}
@@ -1,112 +0,0 @@
use crate::function_tool::FunctionCallError;
use crate::tools::context::FunctionToolOutput;
use crate::tools::context::ToolInvocation;
use crate::tools::context::ToolPayload;
use crate::tools::context::boxed_tool_output;
use crate::tools::handlers::parse_arguments;
use crate::tools::registry::CoreToolRuntime;
use crate::tools::registry::ToolExecutor;
use codex_protocol::items::AgentMessageContent;
use codex_protocol::items::AgentMessageDelivery;
use codex_protocol::items::AgentMessageItem;
use codex_protocol::items::TurnItem;
use codex_protocol::models::MessagePhase;
use codex_tools::JsonSchema;
use codex_tools::ResponsesApiTool;
use codex_tools::ToolName;
use codex_tools::ToolSpec;
use serde::Deserialize;
use std::collections::BTreeMap;
const TOOL_NAME: &str = "send_user_message_async";
pub struct SendUserMessageAsyncHandler {
pub description: Option<String>,
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct SendUserMessageAsyncArgs {
message: String,
}
impl ToolExecutor<ToolInvocation> for SendUserMessageAsyncHandler {
fn tool_name(&self) -> ToolName {
ToolName::plain(TOOL_NAME)
}
fn spec(&self) -> ToolSpec {
let properties = BTreeMap::from([(
"message".to_string(),
JsonSchema::string(Some(
"The concise question to send to the user.".to_string(),
)),
)]);
ToolSpec::Function(ResponsesApiTool {
name: TOOL_NAME.to_string(),
description: self.description.clone().unwrap_or_else(|| {
"Send a concise message that needs the user's attention during ongoing work. The tool returns immediately without ending the turn or waiting for a reply; any reply arrives asynchronously as a new user message.\nOnly use this tool to ask for missing information, preferences, constraints, clarification, or approval. The message should be concise, easy to read and understand, and at the right level of abstraction that is appropriate for the user and task at hand."
.to_string()
}),
strict: false,
defer_loading: None,
parameters: JsonSchema::object(
properties,
Some(vec!["message".to_string()]),
/*additional_properties*/ Some(false.into()),
),
output_schema: None,
})
}
fn handle<'a>(&'a self, invocation: ToolInvocation) -> codex_tools::ToolExecutorFuture<'a>
where
ToolInvocation: 'a,
{
Box::pin(async move {
let ToolInvocation {
session,
turn,
call_id,
payload,
..
} = invocation;
let ToolPayload::Function { arguments } = payload else {
return Err(FunctionCallError::RespondToModel(format!(
"{TOOL_NAME} handler received unsupported payload"
)));
};
let args: SendUserMessageAsyncArgs = parse_arguments(&arguments)?;
let message = args.message.trim();
if message.is_empty() {
return Err(FunctionCallError::RespondToModel(
"message must not be empty".to_string(),
));
}
let item = TurnItem::AgentMessage(AgentMessageItem {
id: call_id,
content: vec![AgentMessageContent::Text {
text: message.to_string(),
}],
phase: Some(MessagePhase::FinalAnswer),
memory_citation: None,
delivery: Some(AgentMessageDelivery::Async),
});
session.emit_turn_item_started(turn.as_ref(), &item).await;
session.emit_turn_item_completed(turn.as_ref(), item).await;
Ok(boxed_tool_output(FunctionToolOutput::from_text(
r#"{"accepted":true}"#.to_string(),
/*success*/ Some(true),
)))
})
}
}
impl CoreToolRuntime for SendUserMessageAsyncHandler {
fn is_builtin_control_tool(&self) -> bool {
true
}
}
+9 -3
View File
@@ -23,8 +23,8 @@ use crate::tools::handlers::PlanHandler;
use crate::tools::handlers::ReadMcpResourceHandler;
use crate::tools::handlers::RequestPermissionsHandler;
use crate::tools::handlers::RequestPluginInstallHandler;
use crate::tools::handlers::RequestUserInputAsyncHandler;
use crate::tools::handlers::RequestUserInputHandler;
use crate::tools::handlers::SendUserMessageAsyncHandler;
use crate::tools::handlers::SleepHandler;
use crate::tools::handlers::TestSyncHandler;
use crate::tools::handlers::ToolSearchHandlerCache;
@@ -1163,10 +1163,16 @@ fn add_core_utility_tools(context: &CoreToolPlanContext<'_>, registry: &mut Tool
.model_info
.experimental_supported_tools
.iter()
.any(|tool| tool == "send_user_message_async")
// Existing model catalogs still advertise the previous name.
.any(|tool| {
matches!(
tool.as_str(),
"request_user_input_async" | "send_user_message_async"
)
})
{
registry.add_with_exposure(
SendUserMessageAsyncHandler {
RequestUserInputAsyncHandler {
description: context
.model_messages
.and_then(|messages| messages.tools.as_ref())