[codex] Add interruptible sleep tool (#28429)

## Why

Models sometimes need to pause briefly while waiting for external work,
but using a shell command for that delay ties the wait to a process and
does not naturally resume when new turn input arrives.

## What changed

- add a built-in `sleep` tool behind the under-development `sleep_tool`
feature
- accept a bounded `duration_ms` argument, matching the millisecond
convention used by unified exec
- end the sleep early when either steered user input or mailbox input
arrives
- include elapsed wall-clock time in completed and interrupted outputs
- emit a dedicated core `SleepItem` through `item/started` and
`item/completed`
- expose the sleep item as app-server v2 `ThreadItem::Sleep` and retain
it in reconstructed thread history
- regenerate the configuration schema for the new feature flag
- regenerate app-server JSON and TypeScript schema fixtures

## Test plan

- `just test -p codex-core sleep_tool_follows_feature_gate`
- `just test -p codex-core any_new_input_interrupts_sleep`
- `just test -p codex-app-server-protocol`
- `just test -p codex-app-server
sleep_emits_started_and_completed_items`

codex-rs/app-server/README.md

@@ -1354,6 +1354,7 @@ Today both notifications carry an empty `items` array even when item events were
 - `collabToolCall` — `{id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}` describing collab tool calls (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`); `status` is `inProgress`, `completed`, or `failed`.
 - `webSearch` — `{id, query, action?}` for a web search request issued by the agent; `action` mirrors the Responses API web_search action payload (`search`, `open_page`, `find_in_page`) and may be omitted until completion.
 - `imageView` — `{id, path}` emitted when the agent invokes the image viewer tool.
+- `sleep` — `{id, durationMs}` emitted while the agent waits for a duration or new input.
 - `enteredReviewMode` — `{id, review}` sent when the reviewer starts; `review` is a short user-facing label such as `"current changes"` or the requested target description.
 - `exitedReviewMode` — `{id, review}` emitted when the reviewer finishes; `review` is the full plain-text review (usually, overall notes plus bullet point findings).
 - `contextCompaction` — `{id}` emitted when codex compacts the conversation history. This can happen automatically.

codex-rs/app-server/tests/suite/v2/mod.rs

@@ -52,6 +52,7 @@ mod request_user_input;
 mod review;
 mod safety_check_downgrade;
 mod skills_list;
+mod sleep;
 mod thread_archive;
 mod thread_delete;
 mod thread_fork;

codex-rs/app-server/tests/suite/v2/sleep.rs

@@ -0,0 +1,174 @@
+use anyhow::Result;
+use app_test_support::TestAppServer;
+use app_test_support::to_response;
+use codex_app_server_protocol::ItemCompletedNotification;
+use codex_app_server_protocol::ItemStartedNotification;
+use codex_app_server_protocol::JSONRPCMessage;
+use codex_app_server_protocol::JSONRPCResponse;
+use codex_app_server_protocol::RequestId;
+use codex_app_server_protocol::ThreadItem;
+use codex_app_server_protocol::ThreadStartParams;
+use codex_app_server_protocol::ThreadStartResponse;
+use codex_app_server_protocol::TurnStartParams;
+use codex_app_server_protocol::TurnStartResponse;
+use codex_app_server_protocol::UserInput as V2UserInput;
+use core_test_support::responses;
+use pretty_assertions::assert_eq;
+use std::path::Path;
+use std::time::Duration;
+use tempfile::TempDir;
+use tokio::time::timeout;
+
+const DEFAULT_READ_TIMEOUT: Duration = Duration::from_secs(10);
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn sleep_emits_started_and_completed_items() -> Result<()> {
+    const CALL_ID: &str = "sleep-1";
+    const DURATION_MS: u64 = 1;
+
+    let server = responses::start_mock_server().await;
+    responses::mount_sse_sequence(
+        &server,
+        vec![
+            responses::sse(vec![
+                responses::ev_response_created("resp-1"),
+                responses::ev_function_call(
+                    CALL_ID,
+                    "sleep",
+                    &serde_json::json!({ "duration_ms": DURATION_MS }).to_string(),
+                ),
+                responses::ev_completed("resp-1"),
+            ]),
+            responses::sse(vec![
+                responses::ev_assistant_message("msg-1", "Done"),
+                responses::ev_completed("resp-2"),
+            ]),
+        ],
+    )
+    .await;
+
+    let codex_home = TempDir::new()?;
+    create_config_toml(codex_home.path(), &server.uri())?;
+
+    let mut mcp = TestAppServer::new(codex_home.path()).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+
+    let thread_start_id = mcp
+        .send_thread_start_request(ThreadStartParams {
+            model: Some("mock-model".to_string()),
+            ..Default::default()
+        })
+        .await?;
+    let thread_start_response: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(thread_start_id)),
+    )
+    .await??;
+    let ThreadStartResponse { thread, .. } = to_response(thread_start_response)?;
+
+    let turn_start_id = mcp
+        .send_turn_start_request(TurnStartParams {
+            thread_id: thread.id.clone(),
+            client_user_message_id: None,
+            input: vec![V2UserInput::Text {
+                text: "Sleep briefly".to_string(),
+                text_elements: Vec::new(),
+            }],
+            ..Default::default()
+        })
+        .await?;
+    let turn_start_response: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(turn_start_id)),
+    )
+    .await??;
+    let TurnStartResponse { turn, .. } = to_response(turn_start_response)?;
+
+    let (started, completed) = timeout(DEFAULT_READ_TIMEOUT, async {
+        let mut started = None;
+        let mut completed = None;
+        while started.is_none() || completed.is_none() {
+            let JSONRPCMessage::Notification(notification) = mcp.read_next_message().await? else {
+                continue;
+            };
+            match notification.method.as_str() {
+                "item/started" => {
+                    let payload: ItemStartedNotification =
+                        serde_json::from_value(notification.params.expect("item/started params"))?;
+                    if matches!(&payload.item, ThreadItem::Sleep { .. }) {
+                        started = Some(payload);
+                    }
+                }
+                "item/completed" => {
+                    let payload: ItemCompletedNotification = serde_json::from_value(
+                        notification.params.expect("item/completed params"),
+                    )?;
+                    if matches!(&payload.item, ThreadItem::Sleep { .. }) {
+                        completed = Some(payload);
+                    }
+                }
+                _ => {}
+            }
+        }
+        Ok::<_, anyhow::Error>((
+            started.expect("sleep started"),
+            completed.expect("sleep completed"),
+        ))
+    })
+    .await??;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("turn/completed"),
+    )
+    .await??;
+
+    let expected_item = ThreadItem::Sleep {
+        id: CALL_ID.to_string(),
+        duration_ms: DURATION_MS,
+    };
+    assert!(completed.completed_at_ms >= started.started_at_ms);
+    assert_eq!(
+        started,
+        ItemStartedNotification {
+            item: expected_item.clone(),
+            thread_id: thread.id.clone(),
+            turn_id: turn.id.clone(),
+            started_at_ms: started.started_at_ms,
+        }
+    );
+    assert_eq!(
+        completed,
+        ItemCompletedNotification {
+            item: expected_item,
+            thread_id: thread.id,
+            turn_id: turn.id,
+            completed_at_ms: completed.completed_at_ms,
+        }
+    );
+
+    Ok(())
+}
+
+fn create_config_toml(codex_home: &Path, server_uri: &str) -> std::io::Result<()> {
+    std::fs::write(
+        codex_home.join("config.toml"),
+        format!(
+            r#"
+model = "mock-model"
+approval_policy = "never"
+sandbox_mode = "read-only"
+model_provider = "mock_provider"
+
+[model_providers.mock_provider]
+name = "Mock provider for test"
+base_url = "{server_uri}/v1"
+wire_api = "responses"
+request_max_retries = 0
+stream_max_retries = 0
+
+[features]
+sleep_tool = true
+"#
+        ),
+    )
+}