lore_cli/capture/watchers/
codex.rs

1//! Codex CLI session parser.
2//!
3//! Parses session files from OpenAI's Codex CLI tool. Sessions are stored in
4//! JSONL format at `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`.
5//!
6//! Each line in a JSONL file has a `type` field:
7//! - `session_meta`: Contains session metadata (id, cwd, model, git info)
8//! - `response_item`: Contains messages with role and content
9
10use anyhow::{Context, Result};
11use chrono::{DateTime, Utc};
12use serde::Deserialize;
13use std::fs::File;
14use std::io::{BufRead, BufReader};
15use std::path::{Path, PathBuf};
16use uuid::Uuid;
17
18use crate::storage::models::{Message, MessageContent, MessageRole, Session};
19
20use super::{Watcher, WatcherInfo};
21
22/// Watcher for Codex CLI sessions.
23///
24/// Discovers and parses JSONL session files from the Codex CLI tool.
25/// Sessions are stored in `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`.
26pub struct CodexWatcher;
27
28impl Watcher for CodexWatcher {
29    fn info(&self) -> WatcherInfo {
30        WatcherInfo {
31            name: "codex",
32            description: "OpenAI Codex CLI",
33            default_paths: vec![codex_sessions_dir()],
34        }
35    }
36
37    fn is_available(&self) -> bool {
38        codex_sessions_dir().exists()
39    }
40
41    fn find_sources(&self) -> Result<Vec<PathBuf>> {
42        find_codex_session_files()
43    }
44
45    fn parse_source(&self, path: &Path) -> Result<Vec<(Session, Vec<Message>)>> {
46        let parsed = parse_codex_session_file(path)?;
47        if parsed.messages.is_empty() {
48            return Ok(vec![]);
49        }
50        let (session, messages) = parsed.to_storage_models();
51        Ok(vec![(session, messages)])
52    }
53
54    fn watch_paths(&self) -> Vec<PathBuf> {
55        vec![codex_sessions_dir()]
56    }
57}
58
59/// Returns the path to the Codex sessions directory.
60///
61/// This is typically `~/.codex/sessions/`.
62fn codex_sessions_dir() -> PathBuf {
63    dirs::home_dir()
64        .unwrap_or_else(|| PathBuf::from("."))
65        .join(".codex")
66        .join("sessions")
67}
68
69/// Raw session metadata from Codex JSONL files.
70#[derive(Debug, Deserialize)]
71struct RawSessionMeta {
72    id: String,
73    #[allow(dead_code)]
74    timestamp: String,
75    cwd: String,
76    #[serde(default)]
77    cli_version: Option<String>,
78    #[serde(default)]
79    model_provider: Option<String>,
80    #[serde(default)]
81    git: Option<RawGitInfo>,
82}
83
84/// Git information from session metadata.
85#[derive(Debug, Deserialize)]
86struct RawGitInfo {
87    #[serde(default)]
88    branch: Option<String>,
89}
90
91/// Raw entry from Codex JSONL files.
92#[derive(Debug, Deserialize)]
93struct RawEntry {
94    timestamp: String,
95    #[serde(rename = "type")]
96    entry_type: String,
97    #[serde(default)]
98    payload: Option<serde_json::Value>,
99}
100
101/// Raw response item payload.
102#[derive(Debug, Deserialize)]
103struct RawResponseItem {
104    #[serde(rename = "type")]
105    item_type: Option<String>,
106    role: Option<String>,
107    #[serde(default)]
108    content: Vec<RawContentItem>,
109}
110
111/// Raw content item within a response.
112#[derive(Debug, Deserialize)]
113struct RawContentItem {
114    #[serde(rename = "type")]
115    content_type: String,
116    #[serde(default)]
117    text: Option<String>,
118}
119
120/// Parses a Codex JSONL session file.
121///
122/// Reads each line of the file and extracts session metadata and messages.
123/// Skips malformed lines rather than failing the entire parse.
124///
125/// # Errors
126///
127/// Returns an error if the file cannot be opened.
128pub fn parse_codex_session_file(path: &Path) -> Result<ParsedCodexSession> {
129    let file = File::open(path).context("Failed to open Codex session file")?;
130    let reader = BufReader::new(file);
131
132    let mut session_id: Option<String> = None;
133    let mut cli_version: Option<String> = None;
134    let mut cwd: Option<String> = None;
135    let mut git_branch: Option<String> = None;
136    let mut model_provider: Option<String> = None;
137    let mut messages: Vec<ParsedCodexMessage> = Vec::new();
138
139    for (line_num, line) in reader.lines().enumerate() {
140        let line = match line {
141            Ok(l) => l,
142            Err(e) => {
143                tracing::debug!("Failed to read line {}: {}", line_num + 1, e);
144                continue;
145            }
146        };
147
148        if line.trim().is_empty() {
149            continue;
150        }
151
152        let entry: RawEntry = match serde_json::from_str(&line) {
153            Ok(e) => e,
154            Err(e) => {
155                tracing::debug!("Skipping unparseable line {}: {}", line_num + 1, e);
156                continue;
157            }
158        };
159
160        match entry.entry_type.as_str() {
161            "session_meta" => {
162                if let Some(payload) = entry.payload {
163                    if let Ok(meta) = serde_json::from_value::<RawSessionMeta>(payload) {
164                        if session_id.is_none() {
165                            session_id = Some(meta.id);
166                        }
167                        if cli_version.is_none() {
168                            cli_version = meta.cli_version;
169                        }
170                        if cwd.is_none() {
171                            cwd = Some(meta.cwd);
172                        }
173                        if model_provider.is_none() {
174                            model_provider = meta.model_provider;
175                        }
176                        if git_branch.is_none() {
177                            git_branch = meta.git.and_then(|g| g.branch);
178                        }
179                    }
180                }
181            }
182            "response_item" => {
183                if let Some(payload) = entry.payload {
184                    if let Ok(item) = serde_json::from_value::<RawResponseItem>(payload) {
185                        // Only process message types
186                        if item.item_type.as_deref() != Some("message") {
187                            continue;
188                        }
189
190                        let role = match item.role.as_deref() {
191                            Some("user") => MessageRole::User,
192                            Some("assistant") => MessageRole::Assistant,
193                            Some("system") => MessageRole::System,
194                            _ => continue,
195                        };
196
197                        // Extract text content from content array
198                        let text: String = item
199                            .content
200                            .iter()
201                            .filter_map(|c| {
202                                if c.content_type == "input_text" || c.content_type == "text" {
203                                    c.text.clone()
204                                } else {
205                                    None
206                                }
207                            })
208                            .collect::<Vec<_>>()
209                            .join("\n");
210
211                        if text.trim().is_empty() {
212                            continue;
213                        }
214
215                        let timestamp = DateTime::parse_from_rfc3339(&entry.timestamp)
216                            .map(|t| t.with_timezone(&Utc))
217                            .unwrap_or_else(|_| Utc::now());
218
219                        messages.push(ParsedCodexMessage {
220                            timestamp,
221                            role,
222                            content: text,
223                        });
224                    }
225                }
226            }
227            _ => {
228                // Skip other entry types
229            }
230        }
231    }
232
233    Ok(ParsedCodexSession {
234        session_id: session_id.unwrap_or_else(|| {
235            path.file_stem()
236                .and_then(|s| s.to_str())
237                .unwrap_or("unknown")
238                .to_string()
239        }),
240        cli_version,
241        cwd: cwd.unwrap_or_else(|| ".".to_string()),
242        git_branch,
243        model_provider,
244        messages,
245        source_path: path.to_string_lossy().to_string(),
246    })
247}
248
249/// Intermediate representation of a parsed Codex session.
250#[derive(Debug)]
251pub struct ParsedCodexSession {
252    pub session_id: String,
253    pub cli_version: Option<String>,
254    pub cwd: String,
255    pub git_branch: Option<String>,
256    pub model_provider: Option<String>,
257    pub messages: Vec<ParsedCodexMessage>,
258    pub source_path: String,
259}
260
261impl ParsedCodexSession {
262    /// Converts this parsed session to storage-ready models.
263    pub fn to_storage_models(&self) -> (Session, Vec<Message>) {
264        let session_uuid = Uuid::parse_str(&self.session_id).unwrap_or_else(|_| Uuid::new_v4());
265
266        let started_at = self
267            .messages
268            .first()
269            .map(|m| m.timestamp)
270            .unwrap_or_else(Utc::now);
271
272        let ended_at = self.messages.last().map(|m| m.timestamp);
273
274        let session = Session {
275            id: session_uuid,
276            tool: "codex".to_string(),
277            tool_version: self.cli_version.clone(),
278            started_at,
279            ended_at,
280            model: self.model_provider.clone(),
281            working_directory: self.cwd.clone(),
282            git_branch: self.git_branch.clone(),
283            source_path: Some(self.source_path.clone()),
284            message_count: self.messages.len() as i32,
285            machine_id: crate::storage::get_machine_id(),
286        };
287
288        let messages: Vec<Message> = self
289            .messages
290            .iter()
291            .enumerate()
292            .map(|(idx, m)| Message {
293                id: Uuid::new_v4(),
294                session_id: session_uuid,
295                parent_id: None,
296                index: idx as i32,
297                timestamp: m.timestamp,
298                role: m.role.clone(),
299                content: MessageContent::Text(m.content.clone()),
300                model: self.model_provider.clone(),
301                git_branch: self.git_branch.clone(),
302                cwd: Some(self.cwd.clone()),
303            })
304            .collect();
305
306        (session, messages)
307    }
308}
309
310/// Intermediate representation of a parsed Codex message.
311#[derive(Debug)]
312pub struct ParsedCodexMessage {
313    pub timestamp: DateTime<Utc>,
314    pub role: MessageRole,
315    pub content: String,
316}
317
318/// Discovers all Codex session files.
319///
320/// Scans `~/.codex/sessions/YYYY/MM/DD/` for `rollout-*.jsonl` files.
321pub fn find_codex_session_files() -> Result<Vec<PathBuf>> {
322    let sessions_dir = codex_sessions_dir();
323
324    if !sessions_dir.exists() {
325        return Ok(Vec::new());
326    }
327
328    let mut files = Vec::new();
329
330    // Walk the directory tree: sessions/YYYY/MM/DD/rollout-*.jsonl
331    for year_entry in std::fs::read_dir(&sessions_dir)? {
332        let year_entry = year_entry?;
333        let year_path = year_entry.path();
334        if !year_path.is_dir() {
335            continue;
336        }
337
338        for month_entry in std::fs::read_dir(&year_path)? {
339            let month_entry = month_entry?;
340            let month_path = month_entry.path();
341            if !month_path.is_dir() {
342                continue;
343            }
344
345            for day_entry in std::fs::read_dir(&month_path)? {
346                let day_entry = day_entry?;
347                let day_path = day_entry.path();
348                if !day_path.is_dir() {
349                    continue;
350                }
351
352                for file_entry in std::fs::read_dir(&day_path)? {
353                    let file_entry = file_entry?;
354                    let file_path = file_entry.path();
355
356                    if let Some(name) = file_path.file_name().and_then(|n| n.to_str()) {
357                        if name.starts_with("rollout-") && name.ends_with(".jsonl") {
358                            files.push(file_path);
359                        }
360                    }
361                }
362            }
363        }
364    }
365
366    Ok(files)
367}
368
369#[cfg(test)]
370mod tests {
371    use super::*;
372    use std::io::Write;
373    use tempfile::NamedTempFile;
374
375    /// Creates a temporary JSONL file with given lines.
376    fn create_temp_session_file(lines: &[&str]) -> NamedTempFile {
377        let mut file = NamedTempFile::new().expect("Failed to create temp file");
378        for line in lines {
379            writeln!(file, "{line}").expect("Failed to write line");
380        }
381        file.flush().expect("Failed to flush");
382        file
383    }
384
385    /// Generate a session_meta line.
386    fn make_session_meta(session_id: &str, cwd: &str, version: &str) -> String {
387        format!(
388            r#"{{"timestamp":"2025-12-18T22:53:29.406Z","type":"session_meta","payload":{{"id":"{session_id}","timestamp":"2025-12-18T22:53:29.377Z","cwd":"{cwd}","originator":"codex_cli_rs","cli_version":"{version}","model_provider":"openai","git":{{"branch":"main"}}}}}}"#
389        )
390    }
391
392    /// Generate a user response_item line.
393    fn make_user_message(content: &str) -> String {
394        format!(
395            r#"{{"timestamp":"2025-12-18T22:54:00.000Z","type":"response_item","payload":{{"type":"message","role":"user","content":[{{"type":"input_text","text":"{content}"}}]}}}}"#
396        )
397    }
398
399    /// Generate an assistant response_item line.
400    fn make_assistant_message(content: &str) -> String {
401        format!(
402            r#"{{"timestamp":"2025-12-18T22:55:00.000Z","type":"response_item","payload":{{"type":"message","role":"assistant","content":[{{"type":"text","text":"{content}"}}]}}}}"#
403        )
404    }
405
406    // Note: Common watcher trait tests (info, watch_paths, find_sources) are in
407    // src/capture/watchers/test_common.rs to avoid duplication across all watchers.
408    // Only tool-specific parsing tests remain here.
409
410    #[test]
411    fn test_parse_session_meta() {
412        let session_id = "019b33ab-179f-7802-88a6-16557b4b7603";
413        let meta_line = make_session_meta(session_id, "/Users/test/project", "0.63.0");
414
415        let file = create_temp_session_file(&[&meta_line]);
416        let parsed = parse_codex_session_file(file.path()).expect("Failed to parse");
417
418        assert_eq!(parsed.session_id, session_id);
419        assert_eq!(parsed.cli_version, Some("0.63.0".to_string()));
420        assert_eq!(parsed.cwd, "/Users/test/project");
421        assert_eq!(parsed.model_provider, Some("openai".to_string()));
422        assert_eq!(parsed.git_branch, Some("main".to_string()));
423    }
424
425    #[test]
426    fn test_parse_user_message() {
427        let session_id = "019b33ab-179f-7802-88a6-16557b4b7603";
428        let meta_line = make_session_meta(session_id, "/test", "0.63.0");
429        let user_line = make_user_message("Hello, can you help me?");
430
431        let file = create_temp_session_file(&[&meta_line, &user_line]);
432        let parsed = parse_codex_session_file(file.path()).expect("Failed to parse");
433
434        assert_eq!(parsed.messages.len(), 1);
435        assert_eq!(parsed.messages[0].role, MessageRole::User);
436        assert_eq!(parsed.messages[0].content, "Hello, can you help me?");
437    }
438
439    #[test]
440    fn test_parse_assistant_message() {
441        let session_id = "019b33ab-179f-7802-88a6-16557b4b7603";
442        let meta_line = make_session_meta(session_id, "/test", "0.63.0");
443        let assistant_line = make_assistant_message("Sure, I can help!");
444
445        let file = create_temp_session_file(&[&meta_line, &assistant_line]);
446        let parsed = parse_codex_session_file(file.path()).expect("Failed to parse");
447
448        assert_eq!(parsed.messages.len(), 1);
449        assert_eq!(parsed.messages[0].role, MessageRole::Assistant);
450        assert_eq!(parsed.messages[0].content, "Sure, I can help!");
451    }
452
453    #[test]
454    fn test_parse_conversation() {
455        let session_id = "019b33ab-179f-7802-88a6-16557b4b7603";
456        let meta_line = make_session_meta(session_id, "/test", "0.63.0");
457        let user_line = make_user_message("Hello");
458        let assistant_line = make_assistant_message("Hi there!");
459
460        let file = create_temp_session_file(&[&meta_line, &user_line, &assistant_line]);
461        let parsed = parse_codex_session_file(file.path()).expect("Failed to parse");
462
463        assert_eq!(parsed.messages.len(), 2);
464        assert_eq!(parsed.messages[0].role, MessageRole::User);
465        assert_eq!(parsed.messages[1].role, MessageRole::Assistant);
466    }
467
468    #[test]
469    fn test_to_storage_models() {
470        let session_id = "019b33ab-179f-7802-88a6-16557b4b7603";
471        let meta_line = make_session_meta(session_id, "/test/project", "0.63.0");
472        let user_line = make_user_message("Hello");
473        let assistant_line = make_assistant_message("Hi!");
474
475        let file = create_temp_session_file(&[&meta_line, &user_line, &assistant_line]);
476        let parsed = parse_codex_session_file(file.path()).expect("Failed to parse");
477        let (session, messages) = parsed.to_storage_models();
478
479        assert_eq!(session.tool, "codex");
480        assert_eq!(session.tool_version, Some("0.63.0".to_string()));
481        assert_eq!(session.working_directory, "/test/project");
482        assert_eq!(session.git_branch, Some("main".to_string()));
483        assert_eq!(session.model, Some("openai".to_string()));
484        assert_eq!(session.message_count, 2);
485
486        assert_eq!(messages.len(), 2);
487        assert_eq!(messages[0].role, MessageRole::User);
488        assert_eq!(messages[1].role, MessageRole::Assistant);
489        assert_eq!(messages[0].index, 0);
490        assert_eq!(messages[1].index, 1);
491    }
492
493    #[test]
494    fn test_empty_lines_skipped() {
495        let session_id = "019b33ab-179f-7802-88a6-16557b4b7603";
496        let meta_line = make_session_meta(session_id, "/test", "0.63.0");
497        let user_line = make_user_message("Hello");
498
499        let file = create_temp_session_file(&["", &meta_line, "  ", &user_line, ""]);
500        let parsed = parse_codex_session_file(file.path()).expect("Failed to parse");
501
502        assert_eq!(parsed.messages.len(), 1);
503    }
504
505    #[test]
506    fn test_invalid_json_skipped() {
507        let session_id = "019b33ab-179f-7802-88a6-16557b4b7603";
508        let meta_line = make_session_meta(session_id, "/test", "0.63.0");
509        let user_line = make_user_message("Hello");
510
511        let file =
512            create_temp_session_file(&["invalid json", &meta_line, "{not valid", &user_line]);
513        let parsed = parse_codex_session_file(file.path()).expect("Failed to parse");
514
515        assert_eq!(parsed.messages.len(), 1);
516        assert_eq!(parsed.session_id, session_id);
517    }
518
519    #[test]
520    fn test_non_message_response_items_skipped() {
521        let session_id = "019b33ab-179f-7802-88a6-16557b4b7603";
522        let meta_line = make_session_meta(session_id, "/test", "0.63.0");
523        // A response_item with type other than "message"
524        let other_item = r#"{"timestamp":"2025-12-18T22:54:00.000Z","type":"response_item","payload":{"type":"function_call","name":"test"}}"#;
525        let user_line = make_user_message("Hello");
526
527        let file = create_temp_session_file(&[&meta_line, other_item, &user_line]);
528        let parsed = parse_codex_session_file(file.path()).expect("Failed to parse");
529
530        assert_eq!(parsed.messages.len(), 1);
531        assert_eq!(parsed.messages[0].role, MessageRole::User);
532    }
533
534    #[test]
535    fn test_empty_content_skipped() {
536        let session_id = "019b33ab-179f-7802-88a6-16557b4b7603";
537        let meta_line = make_session_meta(session_id, "/test", "0.63.0");
538        let empty_content = r#"{"timestamp":"2025-12-18T22:54:00.000Z","type":"response_item","payload":{"type":"message","role":"user","content":[]}}"#;
539        let user_line = make_user_message("Hello");
540
541        let file = create_temp_session_file(&[&meta_line, empty_content, &user_line]);
542        let parsed = parse_codex_session_file(file.path()).expect("Failed to parse");
543
544        assert_eq!(parsed.messages.len(), 1);
545    }
546
547    #[test]
548    fn test_watcher_parse_source() {
549        let watcher = CodexWatcher;
550        let session_id = "019b33ab-179f-7802-88a6-16557b4b7603";
551        let meta_line = make_session_meta(session_id, "/test", "0.63.0");
552        let user_line = make_user_message("Hello");
553
554        let file = create_temp_session_file(&[&meta_line, &user_line]);
555        let result = watcher
556            .parse_source(file.path())
557            .expect("Should parse successfully");
558
559        assert_eq!(result.len(), 1);
560        let (session, messages) = &result[0];
561        assert_eq!(session.tool, "codex");
562        assert_eq!(messages.len(), 1);
563    }
564
565    #[test]
566    fn test_watcher_parse_source_empty_session() {
567        let watcher = CodexWatcher;
568        let session_id = "019b33ab-179f-7802-88a6-16557b4b7603";
569        let meta_line = make_session_meta(session_id, "/test", "0.63.0");
570
571        // Only metadata, no messages
572        let file = create_temp_session_file(&[&meta_line]);
573        let result = watcher
574            .parse_source(file.path())
575            .expect("Should parse successfully");
576
577        assert!(result.is_empty());
578    }
579
580    #[test]
581    fn test_session_id_fallback_to_filename() {
582        // File with no session_meta
583        let user_line = make_user_message("Hello");
584        let file = create_temp_session_file(&[&user_line]);
585        let parsed = parse_codex_session_file(file.path()).expect("Failed to parse");
586
587        // Should fall back to filename
588        assert!(!parsed.session_id.is_empty());
589    }
590
591    #[test]
592    fn test_uuid_session_id_parsing() {
593        let session_id = "019b33ab-179f-7802-88a6-16557b4b7603";
594        let meta_line = make_session_meta(session_id, "/test", "0.63.0");
595        let user_line = make_user_message("Hello");
596
597        let file = create_temp_session_file(&[&meta_line, &user_line]);
598        let parsed = parse_codex_session_file(file.path()).expect("Failed to parse");
599        let (session, _) = parsed.to_storage_models();
600
601        // The session ID should be parsed as a valid UUID
602        assert_eq!(session.id.to_string(), session_id);
603    }
604
605    #[test]
606    fn test_invalid_uuid_generates_new() {
607        let meta_line = r#"{"timestamp":"2025-12-18T22:53:29.406Z","type":"session_meta","payload":{"id":"not-a-uuid","timestamp":"2025-12-18T22:53:29.377Z","cwd":"/test","cli_version":"0.63.0"}}"#;
608        let user_line = make_user_message("Hello");
609
610        let file = create_temp_session_file(&[meta_line, &user_line]);
611        let parsed = parse_codex_session_file(file.path()).expect("Failed to parse");
612        let (session, _) = parsed.to_storage_models();
613
614        // Should still have a valid UUID (newly generated)
615        assert!(!session.id.is_nil());
616    }
617}
lore_cli/capture/watchers/codex.rs

lore_cli/capture/watchers/
codex.rs
