Lightweight coding agent that runs in your terminal
Rust
Expose tool dispatch and timing observations to extensions (#47662)
Ruslan Nigmatullina79a18cd0eb8
diff --git a/codex-rs/core/src/tools/code_mode/execute_handler.rs b/codex-rs/core/src/tools/code_mode/execute_handler.rsindex 2f98e9e173..d1d0df755f 100644--- a/codex-rs/core/src/tools/code_mode/execute_handler.rs+++ b/codex-rs/core/src/tools/code_mode/execute_handler.rs@@ -214,8 +214,7 @@ impl CodeModeExecuteHandler {} = invocation;let mut telemetry = CodeModeToolCallGuard::new(- session.services.analytics_events_client.clone(),- session.thread_id.to_string(),+ &session,turn.sub_id.clone(),turn.turn_metadata_state.clone(),call_id.clone(),diff --git a/codex-rs/core/src/tools/code_mode/telemetry.rs b/codex-rs/core/src/tools/code_mode/telemetry.rsindex ad80a0b799..6e851aa356 100644--- a/codex-rs/core/src/tools/code_mode/telemetry.rs+++ b/codex-rs/core/src/tools/code_mode/telemetry.rs@@ -20,12 +20,12 @@ pub(super) struct CodeModeToolCallGuard {started_at_ms: u64,status: CodeModeToolCallStatus,handler_span: Span,+ extensions: Arc<codex_extension_api::ExtensionRegistry<crate::config::Config>>,}impl CodeModeToolCallGuard {pub(super) fn new(- analytics: AnalyticsEventsClient,- thread_id: String,+ session: &crate::session::session::Session,turn_id: String,turn_metadata: Arc<dyn TurnAnalyticsMetadata>,call_id: String,@@ -33,8 +33,8 @@ impl CodeModeToolCallGuard {handler_span: Span,) -> Self {Self {- analytics,- thread_id,+ analytics: session.services.analytics_events_client.clone(),+ thread_id: session.thread_id.to_string(),turn_id,turn_metadata,call_id,@@ -43,6 +43,7 @@ impl CodeModeToolCallGuard {started_at_ms: codex_analytics::now_unix_millis(),status: CodeModeToolCallStatus::Interrupted,handler_span,+ extensions: Arc::clone(&session.services.extensions),}}@@ -58,6 +59,15 @@ impl CodeModeToolCallGuard {}pub(super) fn record_code_mode_host_duration(&self, duration: Duration) {+ for observer in self.extensions.tool_lifecycle_contributors() {+ observer.on_tool_timing(codex_extension_api::ToolTimingInput {+ thread_id: &self.thread_id,+ turn_id: &self.turn_id,+ call_id: &self.call_id,+ boundary: codex_extension_api::ToolTimingBoundary::HostOperation,+ duration,+ });+ }let Ok(code_mode_host_duration_ns) = u64::try_from(duration.as_nanos()) else {return;};diff --git a/codex-rs/core/src/tools/code_mode/wait_handler.rs b/codex-rs/core/src/tools/code_mode/wait_handler.rsindex 617e412a57..0a7a633b7a 100644--- a/codex-rs/core/src/tools/code_mode/wait_handler.rs+++ b/codex-rs/core/src/tools/code_mode/wait_handler.rs@@ -105,8 +105,7 @@ impl CodeModeWaitHandler {} = invocation;let mut telemetry = CodeModeToolCallGuard::new(- session.services.analytics_events_client.clone(),- session.thread_id.to_string(),+ &session,turn.sub_id.clone(),turn.turn_metadata_state.clone(),call_id.clone(),diff --git a/codex-rs/core/src/tools/parallel.rs b/codex-rs/core/src/tools/parallel.rsindex 53ddadc403..593cbed51a 100644--- a/codex-rs/core/src/tools/parallel.rs+++ b/codex-rs/core/src/tools/parallel.rs@@ -38,6 +38,7 @@ struct ToolCallTimingGuard {turn_id: String,call_id: String,tool_name: codex_tools::ToolName,+ extensions: Arc<codex_extension_api::ExtensionRegistry<crate::config::Config>>,}#[derive(Clone)]@@ -143,14 +144,24 @@ impl ToolCallRuntime {let lock = Arc::clone(&self.parallel_execution);let invocation_cancellation_token = cancellation_token.clone();let started = Instant::now();- let tool_call_timing_guard = ToolCallTimingGuard::capture(+ let mut tool_call_timing_guard = ToolCallTimingGuard::capture(started,&session.thread_id,&turn.sub_id,&call,&source,- turn.config.code_mode.experimental_show_cell_overhead,+ Arc::clone(&session.services.extensions),);+ if let Some(guard) = tool_call_timing_guard.as_mut() {+ for observer in session.services.extensions.tool_lifecycle_contributors() {+ observer.on_tool_dispatch(codex_extension_api::ToolDispatchInput {+ thread_id: &guard.conversation_id,+ turn_id: &guard.turn_id,+ call_id: &guard.call_id,+ tool_name: &guard.tool_name,+ });+ }+ }let execution_started_at = tool_call_timing_guard.as_ref().map(|timing| Arc::clone(&timing.execution_started_at));@@ -340,7 +351,7 @@ impl ToolCallTimingGuard {turn_id: &str,call: &ToolCall,source: &ToolCallSource,- experimental_show_cell_overhead: bool,+ extensions: Arc<codex_extension_api::ExtensionRegistry<crate::config::Config>>,) -> Option<Self> {// Code-mode calls are nested within a direct code-mode tool call whose// timing already includes them. Suppress nested guards so consumers do@@ -348,8 +359,7 @@ impl ToolCallTimingGuard {if !matches!(source,ToolCallSource::Direct | ToolCallSource::DirectPlaintextMessage- ) || (!experimental_show_cell_overhead && !tracing::enabled!(tracing::Level::INFO))- {+ ) {return None;}@@ -360,6 +370,7 @@ impl ToolCallTimingGuard {turn_id: turn_id.to_string(),call_id: call.call_id.clone(),tool_name: call.tool_name.clone(),+ extensions,})}@@ -375,6 +386,17 @@ impl ToolCallTimingGuard {.get().copied().filter(|execution_started_at| *execution_started_at <= completed_at);+ for observer in self.extensions.tool_lifecycle_contributors() {+ observer.on_tool_timing(codex_extension_api::ToolTimingInput {+ thread_id: &self.conversation_id,+ turn_id: &self.turn_id,+ call_id: &self.call_id,+ boundary: codex_extension_api::ToolTimingBoundary::Handler,+ duration: execution_started_at+ .map(|start| completed_at.duration_since(start))+ .unwrap_or_default(),+ });+ }let duration_ms = |duration: std::time::Duration| u64::try_from(duration.as_millis()).ok();let total_duration_ms = duration_ms(completed_at.duration_since(started_at));let dispatch_duration_ms = execution_started_at.map_or_else(@@ -470,7 +492,7 @@ mod tests {"turn-id",&call,&ToolCallSource::Direct,- /*experimental_show_cell_overhead*/ false,+ codex_extension_api::empty_extension_registry(),);assert!(direct_guard.is_some(),@@ -487,7 +509,7 @@ mod tests {cell_id: "cell-1".to_string(),runtime_tool_call_id: "runtime-call-1".to_string(),},- /*experimental_show_cell_overhead*/ false,+ codex_extension_api::empty_extension_registry(),);assert!(code_mode_guard.is_none(),@@ -514,7 +536,7 @@ mod tests {"turn-id",&call,&ToolCallSource::Direct,- /*experimental_show_cell_overhead*/ true,+ codex_extension_api::empty_extension_registry(),).expect("model-visible timing must not depend on INFO logging");timing@@ -785,3 +807,7 @@ mod tests {Ok(())}}++#[cfg(test)]+#[path = "parallel_observation_tests.rs"]+mod observation_tests;diff --git a/codex-rs/core/src/tools/parallel_observation_tests.rs b/codex-rs/core/src/tools/parallel_observation_tests.rsnew file mode 100644index 0000000000..a2f8711ece--- /dev/null+++ b/codex-rs/core/src/tools/parallel_observation_tests.rs@@ -0,0 +1,46 @@+//! Outer tool timing observations work without enabling textual tracing.+use super::*;+use codex_extension_api::ToolLifecycleContributor;+use codex_extension_api::ToolTimingInput;+use pretty_assertions::assert_eq;+use std::sync::Mutex;+use std::time::Duration;++#[derive(Default)]+struct Observer(Mutex<Vec<(String, Duration)>>);+impl ToolLifecycleContributor for Observer {+ fn on_tool_timing(&self, input: ToolTimingInput<'_>) {+ self.0+ .lock()+ .unwrap()+ .push((input.call_id.to_string(), input.duration));+ }+}+#[test]+fn cancelled_dispatch_reports_zero_handler_work_even_without_tracing() {+ let observer = Arc::new(Observer::default());+ let call = ToolCall {+ tool_name: codex_tools::ToolName::plain("tool"),+ call_id: "call".into(),+ payload: ToolPayload::Function {+ arguments: "{}".into(),+ },+ encrypted_function_args: None,+ };+ let mut extensions = codex_extension_api::ExtensionRegistryBuilder::new();+ extensions.tool_lifecycle_contributor(observer.clone());+ let guard = ToolCallTimingGuard::capture(+ Instant::now(),+ &"thread",+ "turn",+ &call,+ &ToolCallSource::Direct,+ Arc::new(extensions.build()),+ )+ .unwrap();+ drop(guard);+ assert_eq!(+ *observer.0.lock().unwrap(),+ vec![("call".into(), Duration::ZERO)]+ );+}diff --git a/codex-rs/core/tests/suite/tool_lifecycle.rs b/codex-rs/core/tests/suite/tool_lifecycle.rsindex 911d9d00f7..060490396b 100644--- a/codex-rs/core/tests/suite/tool_lifecycle.rs+++ b/codex-rs/core/tests/suite/tool_lifecycle.rs@@ -51,6 +51,9 @@ use wiremock::Request;use wiremock::ResponseTemplate;use wiremock::matchers::body_partial_json;+#[path = "tool_observation_tests.rs"]+mod observations;+#[path = "command_lifecycle_tests.rs"]mod command_lifecycle;diff --git a/codex-rs/core/tests/suite/tool_observation_tests.rs b/codex-rs/core/tests/suite/tool_observation_tests.rsnew file mode 100644index 0000000000..429f75882a--- /dev/null+++ b/codex-rs/core/tests/suite/tool_observation_tests.rs@@ -0,0 +1,220 @@+//! Observe real dispatch, completion, cancellation, and nested code-mode execution.+use super::*;+use codex_extension_api::ToolDispatchInput;+use codex_extension_api::ToolFinishInput;+use codex_extension_api::ToolTimingBoundary;+use codex_extension_api::ToolTimingInput;+use codex_protocol::protocol::Op;+use pretty_assertions::assert_eq;+use test_case::test_case;++#[derive(Default)]+struct Observations {+ events: Mutex<Vec<(String, &'static str)>>,+ pause: bool,+ started: Notify,+ timed: Notify,+}++impl ToolLifecycleContributor for Observations {+ fn on_tool_dispatch(&self, input: ToolDispatchInput<'_>) {+ self.events+ .lock()+ .expect("observation lock should not be poisoned")+ .push((input.call_id.into(), "dispatch"));+ }++ fn on_tool_start<'a>(&'a self, input: ToolStartInput<'a>) -> ToolLifecycleFuture<'a> {+ Box::pin(async move {+ self.events+ .lock()+ .expect("observation lock should not be poisoned")+ .push((input.call_id.into(), "start"));+ self.started.notify_one();+ if self.pause {+ std::future::pending::<()>().await;+ }+ })+ }++ fn on_tool_finish<'a>(&'a self, input: ToolFinishInput<'a>) -> ToolLifecycleFuture<'a> {+ Box::pin(async move {+ self.events+ .lock()+ .expect("observation lock should not be poisoned")+ .push((input.call_id.into(), "finish"));+ })+ }++ fn on_tool_timing(&self, input: ToolTimingInput<'_>) {+ let boundary = match input.boundary {+ ToolTimingBoundary::Handler => "handler",+ ToolTimingBoundary::HostOperation => "host",+ };+ self.events+ .lock()+ .expect("observation lock should not be poisoned")+ .push((input.call_id.into(), boundary));+ self.timed.notify_one();+ }+}++#[test_case("update_plan", &["dispatch", "start", "finish", "handler"]; "completed")]+#[test_case("missing_tool", &["dispatch", "handler"]; "rejected_before_start")]+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]+async fn dispatch_and_timing_surround_tool_execution(+ tool_name: &str,+ expected: &[&str],+) -> Result<()> {+ let server = responses::start_mock_server().await;+ let requests = responses::mount_sse_sequence(+ &server,+ vec![+ responses::sse(vec![+ responses::ev_function_call("plan", tool_name, &json!({"plan": []}).to_string()),+ responses::ev_completed("first"),+ ]),+ responses::sse(vec![+ responses::ev_assistant_message("answer", "done"),+ responses::ev_completed("last"),+ ]),+ ],+ )+ .await;+ let observations = Arc::new(Observations::default());+ let mut extensions = ExtensionRegistryBuilder::<Config>::new();+ extensions.tool_lifecycle_contributor(observations.clone());+ let test = test_codex()+ .with_extensions(Arc::new(extensions.build()))+ .with_config(|config| config.update_plan_enabled = true)+ .build_with_auto_env(&server)+ .await?;+ test.submit_text_turn("update the plan").await?;+ assert_eq!(requests.requests().len(), 2);+ assert_eq!(+ *observations+ .events+ .lock()+ .expect("observation lock should not be poisoned"),+ expected+ .iter()+ .map(|event| ("plan".into(), *event))+ .collect::<Vec<_>>()+ );+ Ok(())+}++#[tokio::test(flavor = "multi_thread", worker_threads = 2)]+async fn cancelled_tool_still_reports_handler_timing() -> Result<()> {+ let server = responses::start_mock_server().await;+ let requests = responses::mount_sse_once(+ &server,+ responses::sse(vec![+ responses::ev_function_call("plan", "update_plan", &json!({"plan": []}).to_string()),+ responses::ev_completed("first"),+ ]),+ )+ .await;+ let observations = Arc::new(Observations {+ pause: true,+ ..Default::default()+ });+ let mut extensions = ExtensionRegistryBuilder::<Config>::new();+ extensions.tool_lifecycle_contributor(observations.clone());+ let test = test_codex()+ .with_extensions(Arc::new(extensions.build()))+ .with_config(|config| config.update_plan_enabled = true)+ .build_with_auto_env(&server)+ .await?;+ test.codex+ .start_or_steer_turn(TurnInputRequest::user_input(vec![UserInput::Text {+ text: "update the plan".into(),+ text_elements: vec![],+ }]))+ .await?;+ timeout(Duration::from_secs(10), observations.started.notified()).await?;+ test.codex.submit(Op::Interrupt).await?;+ timeout(Duration::from_secs(10), observations.timed.notified()).await?;+ assert_eq!(requests.requests().len(), 1);+ assert_eq!(+ *observations+ .events+ .lock()+ .expect("observation lock should not be poisoned"),+ vec![+ ("plan".into(), "dispatch"),+ ("plan".into(), "start"),+ ("plan".into(), "finish"),+ ("plan".into(), "handler"),+ ]+ );+ Ok(())+}++#[tokio::test(flavor = "multi_thread", worker_threads = 2)]+async fn code_mode_reports_host_timing_without_nested_dispatch_timing() -> Result<()> {+ let server = responses::start_mock_server().await;+ let requests = responses::mount_sse_sequence(+ &server,+ vec![+ responses::sse(vec![+ responses::ev_custom_tool_call(+ "exec",+ "exec",+ "text(await tools.test_sync_tool({sleep_after_ms: 1}));",+ ),+ responses::ev_completed("first"),+ ]),+ responses::sse(vec![+ responses::ev_assistant_message("answer", "done"),+ responses::ev_completed("last"),+ ]),+ ],+ )+ .await;+ let observations = Arc::new(Observations::default());+ let mut extensions = ExtensionRegistryBuilder::<Config>::new();+ extensions.tool_lifecycle_contributor(observations.clone());+ let test = test_codex()+ .with_extensions(Arc::new(extensions.build()))+ .with_model("test-gpt-5.1-codex")+ .with_config(|config| {+ config+ .features+ .enable(Feature::CodeMode)+ .expect("code mode should be enabled");+ })+ .build_with_auto_env(&server)+ .await?;+ test.submit_text_turn("run the nested tool").await?;+ let requests = requests.requests();+ assert_eq!(requests.len(), 2);+ let events = observations+ .events+ .lock()+ .expect("observation lock should not be poisoned");+ let outer = events+ .iter()+ .filter(|(id, _)| id == "exec")+ .cloned()+ .collect::<Vec<_>>();+ assert_eq!(+ outer,+ vec![+ ("exec".into(), "dispatch"),+ ("exec".into(), "start"),+ ("exec".into(), "host"),+ ("exec".into(), "finish"),+ ("exec".into(), "handler"),+ ],+ "tool output: {:?}",+ requests[1].custom_tool_call_output("exec")+ );+ let nested = events+ .iter()+ .filter(|(id, _)| id != "exec")+ .map(|(_, event)| *event)+ .collect::<Vec<_>>();+ assert_eq!(nested, vec!["start", "finish"]);+ Ok(())+}diff --git a/codex-rs/ext/extension-api/src/contributors.rs b/codex-rs/ext/extension-api/src/contributors.rsindex 6b5acb267f..10508fc1b2 100644--- a/codex-rs/ext/extension-api/src/contributors.rs+++ b/codex-rs/ext/extension-api/src/contributors.rs@@ -50,6 +50,8 @@ pub use tool_lifecycle::ToolCallOutcome;pub use tool_lifecycle::ToolFinishInput;pub use tool_lifecycle::ToolLifecycleFuture;pub use tool_lifecycle::ToolStartInput;+pub use tool_lifecycle::ToolTimingBoundary;+pub use tool_lifecycle::ToolTimingInput;pub use turn_input::TurnInputContext;pub use turn_input::TurnInputEnvironment;pub use turn_lifecycle::TurnAbortInput;@@ -349,6 +351,10 @@ pub trait ToolContributor: Send + Sync {/// rewriting the invocation. Use `ToolContributor` for owning a tool implementation/// and hooks for policy that changes tool payloads.pub trait ToolLifecycleContributor: Send + Sync {+ /// Observe direct calls before readiness, dispatch waiting, and hooks, including blocked calls.+ /// Excludes nested code-mode calls. Observers must return promptly.+ fn on_tool_dispatch(&self, _input: ToolDispatchInput<'_>) {}+/// Called after pre-tool hooks finalize an invocation and before execution.////// Calls blocked by hooks, or whose hook-provided input cannot be applied,@@ -377,6 +383,10 @@ pub trait ToolLifecycleContributor: Send + Sync {fn on_tool_finish<'a>(&'a self, _input: ToolFinishInput<'a>) -> ToolLifecycleFuture<'a> {Box::pin(std::future::ready(()))}++ /// Observe handler or remote host duration as defined by `ToolTimingBoundary`.+ /// Handler timing includes cancellation. Observers must return promptly.+ fn on_tool_timing(&self, _input: ToolTimingInput<'_>) {}}/// Owns the complete approval decision, including whether to consult a reviewer.@@ -404,3 +414,5 @@ pub trait TurnItemContributor: Send + Sync {item: &'a mut TurnItem,) -> ExtensionFuture<'a, Result<(), String>>;}++pub use tool_lifecycle::ToolDispatchInput;diff --git a/codex-rs/ext/extension-api/src/contributors/tool_lifecycle.rs b/codex-rs/ext/extension-api/src/contributors/tool_lifecycle.rsindex 79e20c8ab5..464389cf66 100644--- a/codex-rs/ext/extension-api/src/contributors/tool_lifecycle.rs+++ b/codex-rs/ext/extension-api/src/contributors/tool_lifecycle.rs@@ -211,3 +211,45 @@ pub struct ToolFinishInput<'a> {/// Host-observed result of the tool call.pub outcome: ToolCallOutcome,}++/// The execution interval represented by a tool timing observation.+#[derive(Clone, Copy, Debug)]+pub enum ToolTimingBoundary {+ /// Elapsed time from admission through the parallel-execution gate until the+ /// outer dispatch completes or is dropped. Includes routing, hooks, policy+ /// checks, and result processing; excludes runtime readiness and gate waiting.+ /// Zero if dispatch never passed the gate.+ Handler,+ /// Duration reported by the code-mode host for its exec or wait operation.+ /// Measures the remote operation rather than the enclosing local dispatch.+ HostOperation,+}++/// A measured tool interval. Handler observations also cover cancellation;+/// host-operation observations are available only when the host reports a duration.+/// Observers must not block.+pub struct ToolTimingInput<'a> {+ /// Thread that owns the tool call.+ pub thread_id: &'a str,+ /// Current turn submission id.+ pub turn_id: &'a str,+ /// Model-visible tool call id used to correlate dispatch and timing observations.+ pub call_id: &'a str,+ /// Execution interval measured by this observation.+ pub boundary: ToolTimingBoundary,+ /// Elapsed time within the specified boundary.+ pub duration: std::time::Duration,+}++/// A direct call entering dispatch, before readiness, hooks, or policy checks.+/// Observers must return promptly and cannot affect tool execution.+pub struct ToolDispatchInput<'a> {+ /// Thread that owns the tool call.+ pub thread_id: &'a str,+ /// Current turn submission id.+ pub turn_id: &'a str,+ /// Model-visible tool call id used to correlate dispatch and timing observations.+ pub call_id: &'a str,+ /// Tool name supplied to dispatch, before pre-tool hooks run.+ pub tool_name: &'a ToolName,+}diff --git a/codex-rs/ext/extension-api/src/lib.rs b/codex-rs/ext/extension-api/src/lib.rsindex 44faae9472..2e6c65f662 100644--- a/codex-rs/ext/extension-api/src/lib.rs+++ b/codex-rs/ext/extension-api/src/lib.rs@@ -82,6 +82,8 @@ pub use contributors::ToolFinishInput;pub use contributors::ToolLifecycleContributor;pub use contributors::ToolLifecycleFuture;pub use contributors::ToolStartInput;+pub use contributors::ToolTimingBoundary;+pub use contributors::ToolTimingInput;pub use contributors::TurnAbortInput;pub use contributors::TurnContextContributionInput;pub use contributors::TurnErrorInput;@@ -106,3 +108,5 @@ pub use user_instructions::LoadInstructionsFuture;pub use user_instructions::LoadedUserInstructions;pub use user_instructions::ThreadInstructionsProvider;pub use user_instructions::UserInstructionsProvider;++pub use contributors::ToolDispatchInput;