chore: introduce codex-common crate (#843)

I started this PR because I wanted to share the `format_duration()`
utility function in `codex-rs/exec/src/event_processor.rs` with the TUI.
The question was: where to put it?

`core` should have as few dependencies as possible, so moving it there
would introduce a dependency on `chrono`, which seemed undesirable.
`core` already had this `cli` feature to deal with a similar situation
around sharing common utility functions, so I decided to:

* make `core` feature-free
* introduce `common`
* `common` can have as many "special interest" features as it needs,
each of which can declare their own deps
* the first two features of common are `cli` and `elapsed`

In practice, this meant updating a number of `Cargo.toml` files,
replacing this line:

```toml
codex-core = { path = "../core", features = ["cli"] }
```

with these:

```toml
codex-core = { path = "../core" }
codex-common = { path = "../common", features = ["cli"] }
```

Moving `format_duration()` into its own file gave it some "breathing
room" to add a unit test, so I had Codex generate some tests and new
support for durations over 1 minute.

codex-rs/common/src/approval_mode_cli_arg.rs

@@ -0,0 +1,73 @@
+//! Standard type to use with the `--approval-mode` CLI option.
+//! Available when the `cli` feature is enabled for the crate.
+
+use clap::ArgAction;
+use clap::Parser;
+use clap::ValueEnum;
+
+use codex_core::config::parse_sandbox_permission_with_base_path;
+use codex_core::protocol::AskForApproval;
+use codex_core::protocol::SandboxPermission;
+
+#[derive(Clone, Copy, Debug, ValueEnum)]
+#[value(rename_all = "kebab-case")]
+pub enum ApprovalModeCliArg {
+    /// Run all commands without asking for user approval.
+    /// Only asks for approval if a command fails to execute, in which case it
+    /// will escalate to the user to ask for un-sandboxed execution.
+    OnFailure,
+
+    /// Only run "known safe" commands (e.g. ls, cat, sed) without
+    /// asking for user approval. Will escalate to the user if the model
+    /// proposes a command that is not allow-listed.
+    UnlessAllowListed,
+
+    /// Never ask for user approval
+    /// Execution failures are immediately returned to the model.
+    Never,
+}
+
+impl From<ApprovalModeCliArg> for AskForApproval {
+    fn from(value: ApprovalModeCliArg) -> Self {
+        match value {
+            ApprovalModeCliArg::OnFailure => AskForApproval::OnFailure,
+            ApprovalModeCliArg::UnlessAllowListed => AskForApproval::UnlessAllowListed,
+            ApprovalModeCliArg::Never => AskForApproval::Never,
+        }
+    }
+}
+
+#[derive(Parser, Debug)]
+pub struct SandboxPermissionOption {
+    /// Specify this flag multiple times to specify the full set of permissions
+    /// to grant to Codex.
+    ///
+    /// ```shell
+    /// codex -s disk-full-read-access \
+    ///       -s disk-write-cwd \
+    ///       -s disk-write-platform-user-temp-folder \
+    ///       -s disk-write-platform-global-temp-folder
+    /// ```
+    ///
+    /// Note disk-write-folder takes a value:
+    ///
+    /// ```shell
+    ///     -s disk-write-folder=$HOME/.pyenv/shims
+    /// ```
+    ///
+    /// These permissions are quite broad and should be used with caution:
+    ///
+    /// ```shell
+    ///     -s disk-full-write-access
+    ///     -s network-full-access
+    /// ```
+    #[arg(long = "sandbox-permission", short = 's', action = ArgAction::Append, value_parser = parse_sandbox_permission)]
+    pub permissions: Option<Vec<SandboxPermission>>,
+}
+
+/// Custom value-parser so we can keep the CLI surface small *and*
+/// still handle the parameterised `disk-write-folder` case.
+fn parse_sandbox_permission(raw: &str) -> std::io::Result<SandboxPermission> {
+    let base_path = std::env::current_dir()?;
+    parse_sandbox_permission_with_base_path(raw, base_path)
+}

codex-rs/common/src/elapsed.rs

@@ -0,0 +1,72 @@
+use chrono::Utc;
+
+/// Returns a string representing the elapsed time since `start_time` like
+/// "1m15s" or "1.50s".
+pub fn format_elapsed(start_time: chrono::DateTime<Utc>) -> String {
+    let elapsed = Utc::now().signed_duration_since(start_time);
+    format_time_delta(elapsed)
+}
+
+fn format_time_delta(elapsed: chrono::TimeDelta) -> String {
+    let millis = elapsed.num_milliseconds();
+    format_elapsed_millis(millis)
+}
+
+pub fn format_duration(duration: std::time::Duration) -> String {
+    let millis = duration.as_millis() as i64;
+    format_elapsed_millis(millis)
+}
+
+fn format_elapsed_millis(millis: i64) -> String {
+    if millis < 1000 {
+        format!("{}ms", millis)
+    } else if millis < 60_000 {
+        format!("{:.2}s", millis as f64 / 1000.0)
+    } else {
+        let minutes = millis / 60_000;
+        let seconds = (millis % 60_000) / 1000;
+        format!("{minutes}m{seconds:02}s")
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use chrono::Duration;
+
+    #[test]
+    fn test_format_time_delta_subsecond() {
+        // Durations < 1s should be rendered in milliseconds with no decimals.
+        let dur = Duration::milliseconds(250);
+        assert_eq!(format_time_delta(dur), "250ms");
+
+        // Exactly zero should still work.
+        let dur_zero = Duration::milliseconds(0);
+        assert_eq!(format_time_delta(dur_zero), "0ms");
+    }
+
+    #[test]
+    fn test_format_time_delta_seconds() {
+        // Durations between 1s (inclusive) and 60s (exclusive) should be
+        // printed with 2-decimal-place seconds.
+        let dur = Duration::milliseconds(1_500); // 1.5s
+        assert_eq!(format_time_delta(dur), "1.50s");
+
+        // 59.999s rounds to 60.00s
+        let dur2 = Duration::milliseconds(59_999);
+        assert_eq!(format_time_delta(dur2), "60.00s");
+    }
+
+    #[test]
+    fn test_format_time_delta_minutes() {
+        // Durations ≥ 1 minute should be printed mmss.
+        let dur = Duration::milliseconds(75_000); // 1m15s
+        assert_eq!(format_time_delta(dur), "1m15s");
+
+        let dur_exact = Duration::milliseconds(60_000); // 1m0s
+        assert_eq!(format_time_delta(dur_exact), "1m00s");
+
+        let dur_long = Duration::milliseconds(3_601_000);
+        assert_eq!(format_time_delta(dur_long), "60m01s");
+    }
+}

codex-rs/common/src/lib.rs

@@ -0,0 +1,10 @@
+#[cfg(feature = "cli")]
+mod approval_mode_cli_arg;
+
+#[cfg(feature = "elapsed")]
+pub mod elapsed;
+
+#[cfg(feature = "cli")]
+pub use approval_mode_cli_arg::ApprovalModeCliArg;
+#[cfg(feature = "cli")]
+pub use approval_mode_cli_arg::SandboxPermissionOption;