Lightweight coding agent that runs in your terminal
Rust
Add a critical-path utility for exclusive duration attribution (#55804)
taohong-oaiaf91f6ef2cd6
diff --git a/codex-rs/Cargo.lock b/codex-rs/Cargo.lockindex a22a6ec662..923eaefa2e 100644--- a/codex-rs/Cargo.lock+++ b/codex-rs/Cargo.lock@@ -5103,6 +5103,13 @@ dependencies = ["toml 0.9.11+spec-1.1.0",]+[[package]]+name = "codex-utils-critical-path"+version = "0.0.0"+dependencies = [+ "pretty_assertions",+]+[[package]]name = "codex-utils-elapsed"version = "0.0.0"diff --git a/codex-rs/Cargo.toml b/codex-rs/Cargo.tomlindex 8392dea799..33c12ad70d 100644--- a/codex-rs/Cargo.toml+++ b/codex-rs/Cargo.toml@@ -125,6 +125,7 @@ members = ["utils/cargo-bin","git-utils","utils/cache",+ "utils/critical-path","utils/git-discovery","utils/image","utils/json-to-toml",diff --git a/codex-rs/utils/critical-path/BUILD.bazel b/codex-rs/utils/critical-path/BUILD.bazelnew file mode 100644index 0000000000..299f272e84--- /dev/null+++ b/codex-rs/utils/critical-path/BUILD.bazel@@ -0,0 +1,6 @@+load("//:defs.bzl", "codex_rust_crate")++codex_rust_crate(+ name = "critical-path",+ crate_name = "codex_utils_critical_path",+)diff --git a/codex-rs/utils/critical-path/Cargo.toml b/codex-rs/utils/critical-path/Cargo.tomlnew file mode 100644index 0000000000..a670985e65--- /dev/null+++ b/codex-rs/utils/critical-path/Cargo.toml@@ -0,0 +1,14 @@+[package]+name = "codex-utils-critical-path"+version.workspace = true+edition.workspace = true+license.workspace = true++[lints]+workspace = true++[lib]+doctest = false++[dev-dependencies]+pretty_assertions.workspace = truediff --git a/codex-rs/utils/critical-path/src/critical_path_tests.rs b/codex-rs/utils/critical-path/src/critical_path_tests.rsnew file mode 100644index 0000000000..937d5bba8e--- /dev/null+++ b/codex-rs/utils/critical-path/src/critical_path_tests.rs@@ -0,0 +1,369 @@+//! Reducer coverage for exclusive attribution, parallel joins, ties, and incomplete evidence.++use super::*;+use pretty_assertions::assert_eq;++#[test]+fn join_replaces_overlapping_work_with_the_full_winning_branch() {+ let turn_start = Instant::now();+ let time_after_turn_start = |milliseconds| turn_start + Duration::from_millis(milliseconds);+ let shared_initial_path = CriticalPath::default().work(+ time_after_turn_start(0),+ time_after_turn_start(100),+ WorkKind::Inference,+ );+ let reviewed_tool_path = shared_initial_path+ .clone()+ .work(+ time_after_turn_start(100),+ time_after_turn_start(300),+ WorkKind::AutoReview,+ )+ .work(+ time_after_turn_start(300),+ time_after_turn_start(400),+ WorkKind::Tools,+ );+ let parallel_tool_path = shared_initial_path.clone().work(+ time_after_turn_start(100),+ time_after_turn_start(700),+ WorkKind::Tools,+ );+ let critical_path = shared_initial_path+ .work(+ time_after_turn_start(100),+ time_after_turn_start(200),+ WorkKind::Inference,+ )+ .join(+ time_after_turn_start(200),+ time_after_turn_start(700),+ reviewed_tool_path.latest(parallel_tool_path),+ );+ assert_eq!(+ critical_path.durations(time_after_turn_start(0), time_after_turn_start(700)),+ PathDurations {+ inference: Duration::from_millis(100),+ tools: Duration::from_millis(600),+ ..PathDurations::default()+ }+ );+}++#[test]+fn nested_serial_dependencies_preserve_exclusive_categories() {+ let turn_start = Instant::now();+ let time_after_turn_start = |milliseconds| turn_start + Duration::from_millis(milliseconds);+ let shared_initial_path = CriticalPath::default().work(+ time_after_turn_start(0),+ time_after_turn_start(100),+ WorkKind::Inference,+ );+ let child_path = shared_initial_path+ .clone()+ .work(+ time_after_turn_start(100),+ time_after_turn_start(300),+ WorkKind::AutoReview,+ )+ .work(+ time_after_turn_start(300),+ time_after_turn_start(400),+ WorkKind::Tools,+ )+ .work(+ time_after_turn_start(400),+ time_after_turn_start(500),+ WorkKind::Inference,+ );+ let critical_path = shared_initial_path+ .work(+ time_after_turn_start(100),+ time_after_turn_start(200),+ WorkKind::Inference,+ )+ .join(+ time_after_turn_start(200),+ time_after_turn_start(600),+ child_path,+ );+ assert_eq!(+ critical_path.durations(time_after_turn_start(0), time_after_turn_start(600)),+ PathDurations {+ inference: Duration::from_millis(200),+ auto_review: Duration::from_millis(200),+ tools: Duration::from_millis(200),+ ..PathDurations::default()+ }+ );+}++#[test]+fn equal_finish_times_select_one_path_without_double_counting() {+ let turn_start = Instant::now();+ let turn_end = turn_start + Duration::from_millis(100);+ let reviewed_tool_path =+ CriticalPath::default().work(turn_start, turn_end, WorkKind::AutoReview);+ let inference_path = CriticalPath::default().work(turn_start, turn_end, WorkKind::Inference);+ // A tie has multiple valid paths. Stable left selection does not sum both.+ assert_eq!(+ reviewed_tool_path+ .clone()+ .latest(inference_path)+ .durations(turn_start, turn_end),+ reviewed_tool_path.durations(turn_start, turn_end)+ );+}++#[test]+fn path_retention_exhaustion_marks_unknown_instead_of_claiming_zero() {+ let turn_start = Instant::now();+ let mut critical_path = CriticalPath::default();+ for segment_index in 0..=MAX_PATH_DEPTH {+ critical_path = critical_path.work(+ turn_start + Duration::from_micros(segment_index as u64),+ turn_start + Duration::from_micros(segment_index as u64 + 1),+ WorkKind::Inference,+ );+ }+ let turn_end = turn_start + Duration::from_micros(MAX_PATH_DEPTH as u64 + 1);+ assert_eq!(+ critical_path.durations(turn_start, turn_end),+ PathDurations {+ unknown: turn_end.duration_since(turn_start),+ ..Default::default()+ }+ );+}++#[test]+fn reviewed_branch_wins_even_when_some_review_overlapped_parent_inference() {+ let turn_start = Instant::now();+ let time_after_turn_start = |milliseconds| turn_start + Duration::from_millis(milliseconds);+ let shared_initial_path = CriticalPath::default().work(+ time_after_turn_start(0),+ time_after_turn_start(100),+ WorkKind::Inference,+ );+ let reviewed_tool_path = shared_initial_path+ .clone()+ .work(+ time_after_turn_start(100),+ time_after_turn_start(300),+ WorkKind::AutoReview,+ )+ .work(+ time_after_turn_start(300),+ time_after_turn_start(400),+ WorkKind::Tools,+ );+ let parallel_tool_path = shared_initial_path.clone().work(+ time_after_turn_start(100),+ time_after_turn_start(350),+ WorkKind::Tools,+ );+ let critical_path = shared_initial_path+ .work(+ time_after_turn_start(100),+ time_after_turn_start(200),+ WorkKind::Inference,+ )+ .join(+ time_after_turn_start(200),+ time_after_turn_start(400),+ reviewed_tool_path.latest(parallel_tool_path),+ );+ assert_eq!(+ critical_path.durations(time_after_turn_start(0), time_after_turn_start(400)),+ PathDurations {+ inference: Duration::from_millis(100),+ auto_review: Duration::from_millis(200),+ tools: Duration::from_millis(100),+ ..Default::default()+ }+ );+}++#[test]+fn durations_clip_work_to_the_window_and_attribute_gaps_to_overhead() {+ let turn_start = Instant::now();+ let time_after_turn_start = |milliseconds| turn_start + Duration::from_millis(milliseconds);+ let critical_path = CriticalPath::default()+ .work(+ time_after_turn_start(10),+ time_after_turn_start(30),+ WorkKind::Inference,+ )+ .work(+ time_after_turn_start(50),+ time_after_turn_start(90),+ WorkKind::AutoReview,+ );++ assert_eq!(+ critical_path.durations(time_after_turn_start(0), time_after_turn_start(100)),+ PathDurations {+ inference: Duration::from_millis(20),+ auto_review: Duration::from_millis(40),+ overhead: Duration::from_millis(40),+ ..PathDurations::default()+ }+ );+ assert_eq!(+ critical_path.durations(time_after_turn_start(20), time_after_turn_start(80)),+ PathDurations {+ inference: Duration::from_millis(10),+ auto_review: Duration::from_millis(30),+ overhead: Duration::from_millis(20),+ ..PathDurations::default()+ }+ );+}++#[test]+fn overlapping_work_only_attributes_time_after_the_existing_path() {+ let turn_start = Instant::now();+ let time_after_turn_start = |milliseconds| turn_start + Duration::from_millis(milliseconds);+ let critical_path = CriticalPath::default()+ .work(+ time_after_turn_start(0),+ time_after_turn_start(10),+ WorkKind::Inference,+ )+ .work(+ time_after_turn_start(5),+ time_after_turn_start(20),+ WorkKind::Tools,+ );++ assert_eq!(+ critical_path.durations(time_after_turn_start(0), time_after_turn_start(20)),+ PathDurations {+ inference: Duration::from_millis(10),+ tools: Duration::from_millis(10),+ ..PathDurations::default()+ }+ );+ assert_eq!(+ critical_path.clone().work(+ time_after_turn_start(5),+ time_after_turn_start(15),+ WorkKind::AutoReview+ ),+ critical_path+ );+ assert_eq!(+ critical_path.clone().work(+ time_after_turn_start(20),+ time_after_turn_start(20),+ WorkKind::Unknown+ ),+ critical_path+ );+}++#[test]+fn long_path_debug_output_is_bounded_on_a_small_stack() {+ // Match a typical 2 MiB worker stack rather than nextest's larger test stack.+ std::thread::Builder::new()+ .stack_size(2 * 1024 * 1024)+ .spawn(|| {+ let start = Instant::now();+ let mut path = CriticalPath::default();+ for index in 0..10_000 {+ path = path.work(+ start + Duration::from_micros(index),+ start + Duration::from_micros(index + 1),+ WorkKind::Inference,+ );+ }+ assert!(format!("{path:?}").len() < 512);+ assert!(format!("{path:#?}").len() < 512);+ })+ .unwrap()+ .join()+ .unwrap();+}++#[test]+fn retained_prefixes_can_be_released_concurrently_on_small_stacks() {+ for _ in 0..8 {+ let start = Instant::now();+ let mut path = CriticalPath::default();+ let mut prefixes = [Vec::new(), Vec::new()];+ for index in 0..MAX_PATH_DEPTH {+ path = path.work(+ start + Duration::from_micros(index as u64),+ start + Duration::from_micros(index as u64 + 1),+ WorkKind::Inference,+ );+ prefixes[index % 2].push(path.clone());+ }+ // Only the workers retain nodes when they begin releasing prefixes.+ drop(path);+ let ready = Arc::new(std::sync::Barrier::new(3));+ let workers = prefixes.map(|mut prefixes| {+ let ready = Arc::clone(&ready);+ std::thread::Builder::new()+ .stack_size(2 * 1024 * 1024)+ .spawn(move || {+ ready.wait();+ // Release newest first so adjacent retained prefixes race+ // to become the last owner of the shared chain.+ while let Some(prefix) = prefixes.pop() {+ drop(prefix);+ }+ })+ .unwrap()+ });+ ready.wait();+ for worker in workers {+ worker.join().unwrap();+ }+ }+}++#[test]+fn human_wait_is_retained_only_on_the_selected_parallel_path() {+ let start = Instant::now();+ let time_after_turn_start = |milliseconds| start + Duration::from_millis(milliseconds);+ let prefix =+ CriticalPath::default().work(start, time_after_turn_start(100), WorkKind::Inference);+ let reviewed_tool = prefix+ .clone()+ .work(+ time_after_turn_start(100),+ time_after_turn_start(200),+ WorkKind::AutoReview,+ )+ .work(+ time_after_turn_start(200),+ time_after_turn_start(500),+ WorkKind::UserWait,+ )+ .work(+ time_after_turn_start(500),+ time_after_turn_start(600),+ WorkKind::Tools,+ );+ let parallel_tool = prefix.clone().work(+ time_after_turn_start(100),+ time_after_turn_start(400),+ WorkKind::Tools,+ );+ let path = prefix.join(+ time_after_turn_start(100),+ time_after_turn_start(600),+ parallel_tool.latest(reviewed_tool),+ );+ assert_eq!(+ path.durations(start, time_after_turn_start(600)),+ PathDurations {+ inference: Duration::from_millis(100),+ auto_review: Duration::from_millis(100),+ user_wait: Duration::from_millis(300),+ tools: Duration::from_millis(100),+ ..PathDurations::default()+ }+ );+}diff --git a/codex-rs/utils/critical-path/src/lib.rs b/codex-rs/utils/critical-path/src/lib.rsnew file mode 100644index 0000000000..439d008120--- /dev/null+++ b/codex-rs/utils/critical-path/src/lib.rs@@ -0,0 +1,181 @@+//! Persistent dependency paths and exclusive attribution over the observed turn interval.+//! History is depth-limited; formatting and destruction never recurse through the chain.++use std::sync::Arc;+use std::time::Duration;+use std::time::Instant;++const MAX_PATH_DEPTH: usize = 16_384;++/// Category attributed to an observed segment of dependency work.+#[derive(Clone, Copy, Debug)]+pub enum WorkKind {+ /// Model inference work on the selected dependency path.+ Inference,+ /// Automatic review work, such as reviewing a tool call before execution.+ AutoReview,+ /// Time awaiting a human answer or approval on the selected dependency path.+ UserWait,+ /// Tool execution work, including work after a dependency join resumes.+ /// This is an aggregate category; tool-specific subtypes such as browser or+ /// computer use are not represented by this calculator.+ Tools,+ /// Time within the observed turn interval not covered by a recorded work segment.+ Overhead,+ /// Work whose category is unavailable, including history collapsed at the depth limit.+ Unknown,+}++/// An immutable observed dependency path. Forks share their prefix; a join+/// retains only the dependency that actually released the waiting operation.+/// Equality compares path identity rather than the contents of each segment.+#[derive(Clone, Default)]+pub struct CriticalPath(Option<Arc<Node>>);++impl std::fmt::Debug for CriticalPath {+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ // Summarize the tail without traversing shared dependency history.+ f.debug_struct("CriticalPath")+ .field("depth", &self.0.as_ref().map_or(0, |node| node.depth))+ .field("end", &self.end())+ .finish()+ }+}++impl PartialEq for CriticalPath {+ fn eq(&self, other: &Self) -> bool {+ match (&self.0, &other.0) {+ (Some(left), Some(right)) => Arc::ptr_eq(left, right),+ (None, None) => true,+ (Some(_), None) | (None, Some(_)) => false,+ }+ }+}++impl Eq for CriticalPath {}++struct Node {+ previous: CriticalPath,+ kind: WorkKind,+ start: Instant,+ end: Instant,+ origin: Instant,+ depth: usize,+}++/// Exclusive time attributed to each category within the requested interval.+#[derive(Debug, Default, PartialEq, Eq)]+pub struct PathDurations {+ pub inference: Duration,+ pub auto_review: Duration,+ pub user_wait: Duration,+ pub tools: Duration,+ pub overhead: Duration,+ pub unknown: Duration,+}++impl PathDurations {+ fn record(&mut self, kind: WorkKind, duration: Duration) {+ let total = match kind {+ WorkKind::Inference => &mut self.inference,+ WorkKind::AutoReview => &mut self.auto_review,+ WorkKind::UserWait => &mut self.user_wait,+ WorkKind::Tools => &mut self.tools,+ WorkKind::Overhead => &mut self.overhead,+ WorkKind::Unknown => &mut self.unknown,+ };+ *total = total.saturating_add(duration);+ }+}++impl CriticalPath {+ /// End of the last recorded segment, or `None` for an empty path.+ pub fn end(&self) -> Option<Instant> {+ self.0.as_ref().map(|node| node.end)+ }++ /// Retain the later-finishing path, choosing `self` on a tie.+ pub fn latest(self, other: Self) -> Self {+ if other.end() > self.end() {+ other+ } else {+ self+ }+ }++ /// Append work after the existing path ends, clipping overlap and ignoring empty segments.+ /// Exceeding the history limit collapses the retained interval into unknown work.+ pub fn work(self, start: Instant, end: Instant, kind: WorkKind) -> Self {+ let start = self.end().map_or(start, |previous| previous.max(start));+ if start >= end {+ return self;+ }+ let origin = self.0.as_ref().map_or(start, |node| node.origin);+ let previous_depth = self.0.as_ref().map_or(0, |node| node.depth);+ let depth = previous_depth + 1;+ if depth > MAX_PATH_DEPTH {+ return Self::default().work(origin, end, WorkKind::Unknown);+ }+ Self(Some(Arc::new(Node {+ previous: self,+ kind,+ start,+ end,+ origin,+ depth,+ })))+ }++ /// Select the full branch that released this join, not just its exposed+ /// waiting tail. Both branches carry their common causal prefix.+ pub fn join(self, start: Instant, end: Instant, dependency: Self) -> Self {+ let path = self.latest(dependency);+ let resumed_at = path.end().unwrap_or(start).max(start);+ path.work(resumed_at, end, WorkKind::Tools)+ }++ /// Attribute the requested interval exclusively, counting unrecorded gaps as overhead.+ pub fn durations(&self, start: Instant, end: Instant) -> PathDurations {+ let mut totals = PathDurations::default();+ let mut path = self;+ let mut end = end;+ while let Some(node) = path.0.as_ref() {+ if end <= start {+ break;+ }+ let segment_end = end.min(node.end);+ let segment_start = start.max(node.start);+ if end > node.end {+ totals.record(WorkKind::Overhead, end.duration_since(start.max(node.end)));+ }+ if segment_start < segment_end {+ totals.record(node.kind, segment_end.duration_since(segment_start));+ }+ end = end.min(node.start);+ path = &node.previous;+ }+ if start < end {+ totals.record(WorkKind::Overhead, end.duration_since(start));+ }+ totals+ }+}++// Long sequential turns must not recursively destroy one Arc per operation.+// into_inner consumes each reference atomically: concurrent releases cannot+// leave an Err(Arc) whose subsequent drop recursively destroys the next node.+impl Drop for Node {+ fn drop(&mut self) {+ let mut previous = self.previous.0.take();+ while let Some(node) = previous {+ let Some(mut node) = Arc::into_inner(node) else {+ break;+ };+ previous = node.previous.0.take();+ }+ }+}++#[cfg(test)]+#[path = "critical_path_tests.rs"]+mod tests;