feat: add support for file_opener option in Rust, similiar to #911 (#957)

This ports the enhancement introduced in
https://github.com/openai/codex/pull/911 (and the fixes in
https://github.com/openai/codex/pull/919) for the TypeScript CLI to the
Rust one.

codex-rs/tui/Cargo.toml

@@ -22,11 +22,14 @@ codex-core = { path = "../core" }
 codex-common = { path = "../common", features = ["cli", "elapsed"] }
 color-eyre = "0.6.3"
 crossterm = { version = "0.28.1", features = ["bracketed-paste"] }
+lazy_static = "1"
 mcp-types = { path = "../mcp-types" }
+path-clean = "1.0.1"
 ratatui = { version = "0.29.0", features = [
     "unstable-widget-ref",
     "unstable-rendered-line-info",
 ] }
+regex = "1"
 serde_json = "1"
 shlex = "1.3.0"
 strum = "0.27.1"
@@ -44,4 +47,7 @@ tracing-subscriber = { version = "0.3.19", features = ["env-filter"] }
 tui-input = "0.11.1"
 tui-markdown = "0.3.3"
 tui-textarea = "0.7.0"
-uuid = { version = "1" }
+uuid = "1"
+
+[dev-dependencies]
+pretty_assertions = "1"

codex-rs/tui/src/chatwidget.rs

@@ -209,11 +209,13 @@ impl ChatWidget<'_> {
                 self.request_redraw();
             }
             EventMsg::AgentMessage(AgentMessageEvent { message }) => {
-                self.conversation_history.add_agent_message(message);
+                self.conversation_history
+                    .add_agent_message(&self.config, message);
                 self.request_redraw();
             }
             EventMsg::AgentReasoning(AgentReasoningEvent { text }) => {
-                self.conversation_history.add_agent_reasoning(text);
+                self.conversation_history
+                    .add_agent_reasoning(&self.config, text);
                 self.request_redraw();
             }
             EventMsg::TaskStarted => {

codex-rs/tui/src/citation_regex.rs

@@ -0,0 +1,22 @@
+#![allow(clippy::expect_used)]
+
+use regex::Regex;
+
+// This is defined in its own file so we can limit the scope of
+// `allow(clippy::expect_used)` because we cannot scope it to the `lazy_static!`
+// macro.
+lazy_static::lazy_static! {
+    /// Regular expression that matches Codex-style source file citations such as:
+    ///
+    /// ```text
+    /// 【F:src/main.rs†L10-L20】
+    /// ```
+    ///
+    /// Capture groups:
+    /// 1. file path (anything except the dagger `†` symbol)
+    /// 2. start line number (digits)
+    /// 3. optional end line (digits or `?`)
+    pub(crate) static ref CITATION_REGEX: Regex = Regex::new(
+        r"【F:([^†]+)†L(\d+)(?:-L(\d+|\?))?】"
+    ).expect("failed to compile citation regex");
+}

codex-rs/tui/src/conversation_history_widget.rs

@@ -183,12 +183,12 @@ impl ConversationHistoryWidget {
         self.add_to_history(HistoryCell::new_user_prompt(message));
     }
 
-    pub fn add_agent_message(&mut self, message: String) {
-        self.add_to_history(HistoryCell::new_agent_message(message));
+    pub fn add_agent_message(&mut self, config: &Config, message: String) {
+        self.add_to_history(HistoryCell::new_agent_message(config, message));
     }
 
-    pub fn add_agent_reasoning(&mut self, text: String) {
-        self.add_to_history(HistoryCell::new_agent_reasoning(text));
+    pub fn add_agent_reasoning(&mut self, config: &Config, text: String) {
+        self.add_to_history(HistoryCell::new_agent_reasoning(config, text));
     }
 
     pub fn add_background_event(&mut self, message: String) {

codex-rs/tui/src/history_cell.rs

@@ -155,19 +155,19 @@ impl HistoryCell {
         HistoryCell::UserPrompt { lines }
     }
 
-    pub(crate) fn new_agent_message(message: String) -> Self {
+    pub(crate) fn new_agent_message(config: &Config, message: String) -> Self {
         let mut lines: Vec<Line<'static>> = Vec::new();
         lines.push(Line::from("codex".magenta().bold()));
-        append_markdown(&message, &mut lines);
+        append_markdown(&message, &mut lines, config);
         lines.push(Line::from(""));
 
         HistoryCell::AgentMessage { lines }
     }
 
-    pub(crate) fn new_agent_reasoning(text: String) -> Self {
+    pub(crate) fn new_agent_reasoning(config: &Config, text: String) -> Self {
         let mut lines: Vec<Line<'static>> = Vec::new();
         lines.push(Line::from("thinking".magenta().italic()));
-        append_markdown(&text, &mut lines);
+        append_markdown(&text, &mut lines, config);
         lines.push(Line::from(""));
 
         HistoryCell::AgentReasoning { lines }

codex-rs/tui/src/lib.rs

@@ -19,6 +19,7 @@ mod app_event;
 mod app_event_sender;
 mod bottom_pane;
 mod chatwidget;
+mod citation_regex;
 mod cli;
 mod conversation_history_widget;
 mod exec_command;

codex-rs/tui/src/markdown.rs

@@ -1,8 +1,32 @@
+use codex_core::config::Config;
+use codex_core::config::UriBasedFileOpener;
 use ratatui::text::Line;
 use ratatui::text::Span;
+use std::borrow::Cow;
+use std::path::Path;
 
-pub(crate) fn append_markdown(markdown_source: &str, lines: &mut Vec<Line<'static>>) {
-    let markdown = tui_markdown::from_str(markdown_source);
+use crate::citation_regex::CITATION_REGEX;
+
+pub(crate) fn append_markdown(
+    markdown_source: &str,
+    lines: &mut Vec<Line<'static>>,
+    config: &Config,
+) {
+    append_markdown_with_opener_and_cwd(markdown_source, lines, config.file_opener, &config.cwd);
+}
+
+fn append_markdown_with_opener_and_cwd(
+    markdown_source: &str,
+    lines: &mut Vec<Line<'static>>,
+    file_opener: UriBasedFileOpener,
+    cwd: &Path,
+) {
+    // Perform citation rewrite *before* feeding the string to the markdown
+    // renderer. When `file_opener` is absent we bypass the transformation to
+    // avoid unnecessary allocations.
+    let processed_markdown = rewrite_file_citations(markdown_source, file_opener, cwd);
+
+    let markdown = tui_markdown::from_str(&processed_markdown);
 
     // `tui_markdown` returns a `ratatui::text::Text` where every `Line` borrows
     // from the input `message` string. Since the `HistoryCell` stores its lines
@@ -28,3 +52,112 @@ pub(crate) fn append_markdown(markdown_source: &str, lines: &mut Vec<Line<'stati
         lines.push(owned_line);
     }
 }
+
+/// Rewrites file citations in `src` into markdown hyperlinks using the
+/// provided `scheme` (`vscode`, `cursor`, etc.). The resulting URI follows the
+/// format expected by VS Code-compatible file openers:
+///
+/// ```text
+/// <scheme>://file<ABS_PATH>:<LINE>
+/// ```
+fn rewrite_file_citations<'a>(
+    src: &'a str,
+    file_opener: UriBasedFileOpener,
+    cwd: &Path,
+) -> Cow<'a, str> {
+    // Map enum values to the corresponding URI scheme strings.
+    let scheme: &str = match file_opener.get_scheme() {
+        Some(scheme) => scheme,
+        None => return Cow::Borrowed(src),
+    };
+
+    CITATION_REGEX.replace_all(src, |caps: &regex::Captures<'_>| {
+        let file = &caps[1];
+        let start_line = &caps[2];
+
+        // Resolve the path against `cwd` when it is relative.
+        let absolute_path = {
+            let p = Path::new(file);
+            let absolute_path = if p.is_absolute() {
+                path_clean::clean(p)
+            } else {
+                path_clean::clean(cwd.join(p))
+            };
+            // VS Code expects forward slashes even on Windows because URIs use
+            // `/` as the path separator.
+            absolute_path.to_string_lossy().replace('\\', "/")
+        };
+
+        // Render as a normal markdown link so the downstream renderer emits
+        // the hyperlink escape sequence (when supported by the terminal).
+        //
+        // In practice, sometimes multiple citations for the same file, but with a
+        // different line number, are shown sequentially, so we:
+        // - include the line number in the label to disambiguate them
+        // - add a space after the link to make it easier to read
+        format!("[{file}:{start_line}]({scheme}://file{absolute_path}:{start_line}) ")
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn citation_is_rewritten_with_absolute_path() {
+        let markdown = "See 【F:/src/main.rs†L42-L50】 for details.";
+        let cwd = Path::new("/workspace");
+        let result = rewrite_file_citations(markdown, UriBasedFileOpener::VsCode, cwd);
+
+        assert_eq!(
+            "See [/src/main.rs:42](vscode://file/src/main.rs:42)  for details.",
+            result
+        );
+    }
+
+    #[test]
+    fn citation_is_rewritten_with_relative_path() {
+        let markdown = "Refer to 【F:lib/mod.rs†L5】 here.";
+        let cwd = Path::new("/home/user/project");
+        let result = rewrite_file_citations(markdown, UriBasedFileOpener::Windsurf, cwd);
+
+        assert_eq!(
+            "Refer to [lib/mod.rs:5](windsurf://file/home/user/project/lib/mod.rs:5)  here.",
+            result
+        );
+    }
+
+    #[test]
+    fn citation_followed_by_space_so_they_do_not_run_together() {
+        let markdown = "TODOs on lines 【F:src/foo.rs†L24】【F:src/foo.rs†L42】";
+        let cwd = Path::new("/home/user/project");
+        let result = rewrite_file_citations(markdown, UriBasedFileOpener::VsCode, cwd);
+
+        assert_eq!(
+            "TODOs on lines [src/foo.rs:24](vscode://file/home/user/project/src/foo.rs:24) [src/foo.rs:42](vscode://file/home/user/project/src/foo.rs:42) ",
+            result
+        );
+    }
+
+    #[test]
+    fn citation_unchanged_without_file_opener() {
+        let markdown = "Look at 【F:file.rs†L1】.";
+        let cwd = Path::new("/");
+        let unchanged = rewrite_file_citations(markdown, UriBasedFileOpener::VsCode, cwd);
+        // The helper itself always rewrites – this test validates behaviour of
+        // append_markdown when `file_opener` is None.
+        let mut out = Vec::new();
+        append_markdown_with_opener_and_cwd(markdown, &mut out, UriBasedFileOpener::None, cwd);
+        // Convert lines back to string for comparison.
+        let rendered: String = out
+            .iter()
+            .flat_map(|l| l.spans.iter())
+            .map(|s| s.content.clone())
+            .collect::<Vec<_>>()
+            .join("");
+        assert_eq!(markdown, rendered);
+        // Ensure helper rewrites.
+        assert_ne!(markdown, unchanged);
+    }
+}