Expose tool dispatch and timing observations to extensions (#47662)

## Why

Tool lifecycle observers need visibility into calls rejected before execution starts and timing that remains available on cancellation, independently of tracing settings.

## What changed

- Add `on_tool_dispatch` and `on_tool_timing` callbacks to `ToolLifecycleContributor`, with thread, turn, and call IDs for correlation.
- Report direct calls before readiness, dispatch waiting, and hooks. Report handler duration when dispatch completes or is dropped, excluding readiness and gate waiting and returning zero if the call never passes the gate.
- Expose code-mode host durations as a separate `HostOperation` timing boundary. Exclude nested code-mode calls from dispatch and handler timing observations to avoid double counting.

## Testing

Add tests for callback ordering on completed and rejected calls, timing on cancellation, zero handler duration before gate admission without tracing, and code-mode host timing without nested dispatch or handler timing observations.

GitOrigin-RevId: 97998b5094564c13cb2cfad089bb0a9d6615eb5c
This commit is contained in:
Ruslan Nigmatullin
2026-09-23 20:49:48 +00:00
committed by copyberry
parent 5bae5b563e
commit a79a18cd0e
10 changed files with 377 additions and 16 deletions
@@ -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(),
+14 -4
View File
@@ -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;
};
@@ -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(),
+34 -8
View File
@@ -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;
@@ -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)]
);
}