toolpath-convo 0.8.0

#![doc = include_str!("../README.md")]

pub mod derive;
pub mod extract;
pub mod project;

pub use derive::{DeriveConfig, derive_path, file_write_diff, unified_diff};

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::path::PathBuf;

// ── Error ────────────────────────────────────────────────────────────

/// Errors from conversation provider operations.
#[derive(Debug, thiserror::Error)]
pub enum ConvoError {
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),

    #[error("JSON error: {0}")]
    Json(#[from] serde_json::Error),

    #[error("provider error: {0}")]
    Provider(String),

    #[error("{0}")]
    Other(#[from] Box<dyn std::error::Error + Send + Sync>),
}

pub type Result<T> = std::result::Result<T, ConvoError>;

// ── Core types ───────────────────────────────────────────────────────

/// Who produced a turn.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum Role {
    User,
    Assistant,
    System,
    /// Provider-specific roles (e.g. "tool", "function").
    Other(String),
}

impl std::fmt::Display for Role {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Role::User => write!(f, "user"),
            Role::Assistant => write!(f, "assistant"),
            Role::System => write!(f, "system"),
            Role::Other(s) => write!(f, "{}", s),
        }
    }
}

/// Token usage for a single turn.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct TokenUsage {
    /// Tokens sent to the model (prompt + context).
    pub input_tokens: Option<u32>,
    /// Tokens generated by the model.
    pub output_tokens: Option<u32>,
    /// Tokens read from cache (prompt caching, context caching).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cache_read_tokens: Option<u32>,
    /// Tokens written to cache.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cache_write_tokens: Option<u32>,
}

/// Snapshot of the working environment when a turn was produced.
///
/// All fields are optional. Providers populate what they have.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct EnvironmentSnapshot {
    /// Working directory (absolute path).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub working_dir: Option<String>,
    /// Version control branch (git, hg, jj, etc.).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub vcs_branch: Option<String>,
    /// Version control revision (commit hash, changeset ID, etc.).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub vcs_revision: Option<String>,
}

/// A sub-agent delegation: a turn that spawned child work.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DelegatedWork {
    /// Provider-specific agent identifier (e.g. session ID, task ID).
    pub agent_id: String,
    /// The prompt/instruction given to the sub-agent.
    pub prompt: String,
    /// Turns produced by the sub-agent (may be empty if not available
    /// or if the sub-agent's work is stored in a separate session).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub turns: Vec<Turn>,
    /// Final result returned by the sub-agent.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub result: Option<String>,
}

/// A non-conversational event from the session (hook result, snapshot, etc.)
///
/// These are provider-specific entries that aren't turns but need to
/// be preserved for round-trip fidelity.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConversationEvent {
    /// Unique identifier (may be synthetic for entries without UUIDs).
    pub id: String,
    /// When this event occurred.
    pub timestamp: String,
    /// Parent event or turn ID (for ordering).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub parent_id: Option<String>,
    /// Event type (e.g., "attachment", "system", "file-history-snapshot").
    pub event_type: String,
    /// Event data — provider-specific key-value pairs.
    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
    pub data: HashMap<String, serde_json::Value>,
}

/// Toolpath's classification of what a tool invocation does.
///
/// This is toolpath's ontology, not a provider-specific label. Provider
/// crates map their tool names into these categories. `None` means the
/// tool isn't recognized — consumers still have `name` and `input` for
/// anything we don't classify.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ToolCategory {
    /// Read a file — no side effects on the filesystem.
    FileRead,
    /// Write, edit, create, or delete a file.
    FileWrite,
    /// Search or discover files by name or content pattern.
    FileSearch,
    /// Shell or terminal command execution.
    Shell,
    /// Network access — web fetch, search, API call.
    Network,
    /// Spawn a sub-agent or delegate work.
    Delegation,
}

/// A tool invocation within a turn.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ToolInvocation {
    /// Provider-assigned identifier for this invocation.
    pub id: String,
    /// Provider-specific tool name (e.g. `"Read"`, `"Bash"`, `"editor"`).
    pub name: String,
    /// Tool input parameters as provider-specific JSON.
    pub input: serde_json::Value,
    /// Populated when the result is available in the same turn.
    pub result: Option<ToolResult>,
    /// Toolpath's classification of this invocation. Set by the provider
    /// crate; `None` for unrecognized tools.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub category: Option<ToolCategory>,
}

/// The result of a tool invocation.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ToolResult {
    /// The text content returned by the tool.
    pub content: String,
    /// Whether the tool reported an error.
    pub is_error: bool,
}

/// A single turn in a conversation, from any provider.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Turn {
    /// Unique identifier within the conversation.
    pub id: String,

    /// Parent turn ID (for branching conversations).
    pub parent_id: Option<String>,

    /// Who produced this turn.
    pub role: Role,

    /// When this turn occurred (ISO 8601).
    pub timestamp: String,

    /// The visible text content (already collapsed from provider-specific formats).
    pub text: String,

    /// Internal reasoning (chain-of-thought, thinking blocks).
    pub thinking: Option<String>,

    /// Tool invocations in this turn.
    pub tool_uses: Vec<ToolInvocation>,

    /// Model identifier (e.g. "claude-opus-4-6", "gpt-4o").
    pub model: Option<String>,

    /// Why the turn ended (e.g. "end_turn", "tool_use", "max_tokens").
    pub stop_reason: Option<String>,

    /// Token usage for this turn.
    pub token_usage: Option<TokenUsage>,

    /// Environment at time of this turn.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub environment: Option<EnvironmentSnapshot>,

    /// Sub-agent work delegated from this turn.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub delegations: Vec<DelegatedWork>,

    /// Provider-specific data that doesn't fit the common schema.
    ///
    /// Providers namespace their data under a provider key (e.g.
    /// `extra["claude"]` for Claude Code) to avoid collisions when
    /// consumers work with multiple providers.
    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
    pub extra: HashMap<String, serde_json::Value>,
}

/// A complete conversation from any provider.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConversationView {
    /// Unique session/conversation identifier.
    pub id: String,

    /// When the conversation started.
    pub started_at: Option<DateTime<Utc>>,

    /// When the conversation was last active.
    pub last_activity: Option<DateTime<Utc>>,

    /// Ordered turns.
    pub turns: Vec<Turn>,

    /// Aggregate token usage across all turns.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub total_usage: Option<TokenUsage>,

    /// Provider identity (e.g. "claude-code", "aider", "codex-cli").
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provider_id: Option<String>,

    /// Files mutated during this conversation, deduplicated, in first-touch order.
    /// Populated by the provider from tool invocation inputs.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub files_changed: Vec<String>,

    /// All session IDs that were merged to produce this view, in
    /// chronological order (oldest segment first). Empty or single-element
    /// for non-chained conversations.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub session_ids: Vec<String>,

    /// Non-conversational events (hooks, snapshots, metadata) in order.
    /// These are provider-specific entries that aren't turns but need to
    /// be preserved for round-trip fidelity.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub events: Vec<ConversationEvent>,
}

impl ConversationView {
    /// Title derived from the first user turn, truncated to `max_len` characters.
    pub fn title(&self, max_len: usize) -> Option<String> {
        let text = self
            .turns
            .iter()
            .find(|t| t.role == Role::User && !t.text.is_empty())
            .map(|t| &t.text)?;

        if text.chars().count() > max_len {
            let truncated: String = text.chars().take(max_len).collect();
            Some(format!("{}...", truncated))
        } else {
            Some(text.clone())
        }
    }

    /// All turns with the given role.
    pub fn turns_by_role(&self, role: &Role) -> Vec<&Turn> {
        self.turns.iter().filter(|t| &t.role == role).collect()
    }

    /// Turns added after the turn with the given ID.
    ///
    /// If the ID is not found, returns all turns. If the ID is the last
    /// turn, returns an empty slice.
    pub fn turns_since(&self, turn_id: &str) -> &[Turn] {
        match self.turns.iter().position(|t| t.id == turn_id) {
            Some(idx) if idx + 1 < self.turns.len() => &self.turns[idx + 1..],
            Some(_) => &[],
            None => &self.turns,
        }
    }
}

/// Lightweight metadata for a conversation (no turns loaded).
///
/// Returned by [`ConversationProvider::load_metadata`] and
/// [`ConversationProvider::list_metadata`] for listing conversations
/// without the cost of loading all turns.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConversationMeta {
    /// Unique session/conversation identifier.
    pub id: String,
    /// When the conversation started.
    pub started_at: Option<DateTime<Utc>>,
    /// When the conversation was last active.
    pub last_activity: Option<DateTime<Utc>>,
    /// Total number of messages (entries) in the conversation.
    pub message_count: usize,
    /// Path to the backing file, if file-based.
    pub file_path: Option<PathBuf>,
    /// Link to the preceding session segment (if this is a continuation).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub predecessor: Option<SessionLink>,
    /// Link to the following session segment (if this was continued).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub successor: Option<SessionLink>,
}

// ── Session chaining ─────────────────────────────────────────────────

/// Why two session files are linked.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum SessionLinkKind {
    /// The provider rotated to a new file (plan-mode exit, context overflow, etc.).
    Rotation,
}

/// A link between two session segments.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SessionLink {
    /// Session ID of the linked segment.
    pub session_id: String,
    /// Why the link exists.
    pub kind: SessionLinkKind,
}

// ── Events ───────────────────────────────────────────────────────────

/// Events emitted by a [`ConversationWatcher`].
///
/// # Dispatch
///
/// Use `match` for exhaustive dispatch — the compiler catches new variants:
///
/// ```
/// use toolpath_convo::WatcherEvent;
///
/// fn handle_events(events: &[WatcherEvent]) {
///     for event in events {
///         match event {
///             WatcherEvent::Turn(turn) => {
///                 println!("new turn {}: {}", turn.id, turn.text);
///             }
///             WatcherEvent::TurnUpdated(turn) => {
///                 println!("updated turn {}: {}", turn.id, turn.text);
///             }
///             WatcherEvent::Progress { kind, data } => {
///                 println!("progress ({}): {}", kind, data);
///             }
///         }
///     }
/// }
/// ```
///
/// Convenience methods ([`as_turn`](WatcherEvent::as_turn),
/// [`turn_id`](WatcherEvent::turn_id), [`is_update`](WatcherEvent::is_update),
/// [`as_progress`](WatcherEvent::as_progress)) are useful when `Turn` and
/// `TurnUpdated` collapse into the same code path or for quick field access.
#[derive(Debug, Clone)]
pub enum WatcherEvent {
    /// A turn seen for the first time.
    Turn(Box<Turn>),

    /// A previously-emitted turn with additional data filled in
    /// (e.g. tool results that arrived in a later log entry).
    ///
    /// Consumers should replace their stored copy of the turn with this
    /// updated version. The turn's `id` field identifies which turn to replace.
    TurnUpdated(Box<Turn>),

    /// A non-conversational progress/status event.
    Progress {
        kind: String,
        data: serde_json::Value,
    },
}

impl WatcherEvent {
    /// Returns the [`Turn`] payload for both [`Turn`](WatcherEvent::Turn)
    /// and [`TurnUpdated`](WatcherEvent::TurnUpdated) variants.
    pub fn as_turn(&self) -> Option<&Turn> {
        match self {
            WatcherEvent::Turn(t) | WatcherEvent::TurnUpdated(t) => Some(t),
            WatcherEvent::Progress { .. } => None,
        }
    }

    /// Returns `(kind, data)` for [`Progress`](WatcherEvent::Progress) events.
    pub fn as_progress(&self) -> Option<(&str, &serde_json::Value)> {
        match self {
            WatcherEvent::Progress { kind, data } => Some((kind, data)),
            _ => None,
        }
    }

    /// Returns `true` only for [`TurnUpdated`](WatcherEvent::TurnUpdated).
    pub fn is_update(&self) -> bool {
        matches!(self, WatcherEvent::TurnUpdated(_))
    }

    /// Returns the turn ID for turn-carrying variants.
    pub fn turn_id(&self) -> Option<&str> {
        self.as_turn().map(|t| t.id.as_str())
    }
}

// ── Traits ───────────────────────────────────────────────────────────

/// Trait for converting provider-specific conversation data into the
/// generic [`ConversationView`].
///
/// Implement this on your provider's manager type (e.g. `ClaudeConvo`).
pub trait ConversationProvider {
    /// List conversation IDs for a project/workspace.
    fn list_conversations(&self, project: &str) -> Result<Vec<String>>;

    /// Load a full conversation as a [`ConversationView`].
    fn load_conversation(&self, project: &str, conversation_id: &str) -> Result<ConversationView>;

    /// Load metadata only (no turns).
    fn load_metadata(&self, project: &str, conversation_id: &str) -> Result<ConversationMeta>;

    /// List metadata for all conversations in a project.
    fn list_metadata(&self, project: &str) -> Result<Vec<ConversationMeta>>;
}

/// Trait for polling conversation updates from any provider.
pub trait ConversationWatcher {
    /// Poll for new events since the last poll.
    fn poll(&mut self) -> Result<Vec<WatcherEvent>>;

    /// Number of turns seen so far.
    fn seen_count(&self) -> usize;
}

pub use extract::extract_conversation;
pub use project::{AnyProjector, ConversationProjector};

// ── Tests ────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;

    fn sample_view() -> ConversationView {
        ConversationView {
            id: "sess-1".into(),
            started_at: None,
            last_activity: None,
            turns: vec![
                Turn {
                    id: "t1".into(),
                    parent_id: None,
                    role: Role::User,
                    timestamp: "2026-01-01T00:00:00Z".into(),
                    text: "Fix the authentication bug in login.rs".into(),
                    thinking: None,
                    tool_uses: vec![],
                    model: None,
                    stop_reason: None,
                    token_usage: None,
                    environment: None,
                    delegations: vec![],
                    extra: HashMap::new(),
                },
                Turn {
                    id: "t2".into(),
                    parent_id: Some("t1".into()),
                    role: Role::Assistant,
                    timestamp: "2026-01-01T00:00:01Z".into(),
                    text: "I'll fix that for you.".into(),
                    thinking: Some("The bug is in the token validation".into()),
                    tool_uses: vec![ToolInvocation {
                        id: "tool-1".into(),
                        name: "Read".into(),
                        input: serde_json::json!({"file": "src/login.rs"}),
                        result: Some(ToolResult {
                            content: "fn login() { ... }".into(),
                            is_error: false,
                        }),
                        category: Some(ToolCategory::FileRead),
                    }],
                    model: Some("claude-opus-4-6".into()),
                    stop_reason: Some("end_turn".into()),
                    token_usage: Some(TokenUsage {
                        input_tokens: Some(100),
                        output_tokens: Some(50),
                        cache_read_tokens: None,
                        cache_write_tokens: None,
                    }),
                    environment: None,
                    delegations: vec![],
                    extra: HashMap::new(),
                },
                Turn {
                    id: "t3".into(),
                    parent_id: Some("t2".into()),
                    role: Role::User,
                    timestamp: "2026-01-01T00:00:02Z".into(),
                    text: "Thanks!".into(),
                    thinking: None,
                    tool_uses: vec![],
                    model: None,
                    stop_reason: None,
                    token_usage: None,
                    environment: None,
                    delegations: vec![],
                    extra: HashMap::new(),
                },
            ],
            total_usage: None,
            provider_id: None,
            files_changed: vec![],
            session_ids: vec![],
            events: vec![],
        }
    }

    #[test]
    fn test_title_short() {
        let view = sample_view();
        let title = view.title(100).unwrap();
        assert_eq!(title, "Fix the authentication bug in login.rs");
    }

    #[test]
    fn test_title_truncated() {
        let view = sample_view();
        let title = view.title(10).unwrap();
        assert_eq!(title, "Fix the au...");
    }

    #[test]
    fn test_title_empty() {
        let view = ConversationView {
            id: "empty".into(),
            started_at: None,
            last_activity: None,
            turns: vec![],
            total_usage: None,
            provider_id: None,
            files_changed: vec![],
            session_ids: vec![],
            events: vec![],
        };
        assert!(view.title(50).is_none());
    }

    #[test]
    fn test_turns_by_role() {
        let view = sample_view();
        let users = view.turns_by_role(&Role::User);
        assert_eq!(users.len(), 2);
        let assistants = view.turns_by_role(&Role::Assistant);
        assert_eq!(assistants.len(), 1);
    }

    #[test]
    fn test_turns_since_middle() {
        let view = sample_view();
        let since = view.turns_since("t1");
        assert_eq!(since.len(), 2);
        assert_eq!(since[0].id, "t2");
    }

    #[test]
    fn test_turns_since_last() {
        let view = sample_view();
        let since = view.turns_since("t3");
        assert!(since.is_empty());
    }

    #[test]
    fn test_turns_since_unknown() {
        let view = sample_view();
        let since = view.turns_since("nonexistent");
        assert_eq!(since.len(), 3);
    }

    #[test]
    fn test_role_display() {
        assert_eq!(Role::User.to_string(), "user");
        assert_eq!(Role::Assistant.to_string(), "assistant");
        assert_eq!(Role::System.to_string(), "system");
        assert_eq!(Role::Other("tool".into()).to_string(), "tool");
    }

    #[test]
    fn test_role_equality() {
        assert_eq!(Role::User, Role::User);
        assert_ne!(Role::User, Role::Assistant);
        assert_eq!(Role::Other("x".into()), Role::Other("x".into()));
        assert_ne!(Role::Other("x".into()), Role::Other("y".into()));
    }

    #[test]
    fn test_turn_serde_roundtrip() {
        let turn = &sample_view().turns[1];
        let json = serde_json::to_string(turn).unwrap();
        let back: Turn = serde_json::from_str(&json).unwrap();
        assert_eq!(back.id, "t2");
        assert_eq!(back.model, Some("claude-opus-4-6".into()));
        assert_eq!(back.tool_uses.len(), 1);
        assert_eq!(back.tool_uses[0].name, "Read");
        assert!(back.tool_uses[0].result.is_some());
    }

    #[test]
    fn test_conversation_view_serde_roundtrip() {
        let view = sample_view();
        let json = serde_json::to_string(&view).unwrap();
        let back: ConversationView = serde_json::from_str(&json).unwrap();
        assert_eq!(back.id, "sess-1");
        assert_eq!(back.turns.len(), 3);
    }

    #[test]
    fn test_watcher_event_variants() {
        let turn_event = WatcherEvent::Turn(Box::new(sample_view().turns[0].clone()));
        assert!(matches!(turn_event, WatcherEvent::Turn(_)));

        let updated_event = WatcherEvent::TurnUpdated(Box::new(sample_view().turns[1].clone()));
        assert!(matches!(updated_event, WatcherEvent::TurnUpdated(_)));

        let progress_event = WatcherEvent::Progress {
            kind: "agent_progress".into(),
            data: serde_json::json!({"status": "running"}),
        };
        assert!(matches!(progress_event, WatcherEvent::Progress { .. }));
    }

    #[test]
    fn test_watcher_event_as_turn() {
        let turn = sample_view().turns[0].clone();
        let event = WatcherEvent::Turn(Box::new(turn.clone()));
        assert_eq!(event.as_turn().unwrap().id, "t1");

        let updated = WatcherEvent::TurnUpdated(Box::new(turn));
        assert_eq!(updated.as_turn().unwrap().id, "t1");

        let progress = WatcherEvent::Progress {
            kind: "test".into(),
            data: serde_json::Value::Null,
        };
        assert!(progress.as_turn().is_none());
    }

    #[test]
    fn test_watcher_event_as_progress() {
        let progress = WatcherEvent::Progress {
            kind: "hook_progress".into(),
            data: serde_json::json!({"hookName": "pre-commit"}),
        };
        let (kind, data) = progress.as_progress().unwrap();
        assert_eq!(kind, "hook_progress");
        assert_eq!(data["hookName"], "pre-commit");

        let turn = WatcherEvent::Turn(Box::new(sample_view().turns[0].clone()));
        assert!(turn.as_progress().is_none());
    }

    #[test]
    fn test_watcher_event_is_update() {
        let turn = WatcherEvent::Turn(Box::new(sample_view().turns[0].clone()));
        assert!(!turn.is_update());

        let updated = WatcherEvent::TurnUpdated(Box::new(sample_view().turns[0].clone()));
        assert!(updated.is_update());

        let progress = WatcherEvent::Progress {
            kind: "test".into(),
            data: serde_json::Value::Null,
        };
        assert!(!progress.is_update());
    }

    #[test]
    fn test_watcher_event_turn_id() {
        let turn = WatcherEvent::Turn(Box::new(sample_view().turns[1].clone()));
        assert_eq!(turn.turn_id(), Some("t2"));

        let updated = WatcherEvent::TurnUpdated(Box::new(sample_view().turns[0].clone()));
        assert_eq!(updated.turn_id(), Some("t1"));

        let progress = WatcherEvent::Progress {
            kind: "test".into(),
            data: serde_json::Value::Null,
        };
        assert!(progress.turn_id().is_none());
    }

    #[test]
    fn test_token_usage_default() {
        let usage = TokenUsage::default();
        assert!(usage.input_tokens.is_none());
        assert!(usage.output_tokens.is_none());
        assert!(usage.cache_read_tokens.is_none());
        assert!(usage.cache_write_tokens.is_none());
    }

    #[test]
    fn test_token_usage_cache_fields_serde() {
        let usage = TokenUsage {
            input_tokens: Some(100),
            output_tokens: Some(50),
            cache_read_tokens: Some(500),
            cache_write_tokens: Some(200),
        };
        let json = serde_json::to_string(&usage).unwrap();
        let back: TokenUsage = serde_json::from_str(&json).unwrap();
        assert_eq!(back.cache_read_tokens, Some(500));
        assert_eq!(back.cache_write_tokens, Some(200));
    }

    #[test]
    fn test_token_usage_cache_fields_omitted() {
        // Old-format JSON without cache fields should deserialize with None
        let json = r#"{"input_tokens":100,"output_tokens":50}"#;
        let usage: TokenUsage = serde_json::from_str(json).unwrap();
        assert_eq!(usage.input_tokens, Some(100));
        assert!(usage.cache_read_tokens.is_none());
        assert!(usage.cache_write_tokens.is_none());
    }

    #[test]
    fn test_environment_snapshot_serde() {
        let env = EnvironmentSnapshot {
            working_dir: Some("/home/user/project".into()),
            vcs_branch: Some("main".into()),
            vcs_revision: Some("abc123".into()),
        };
        let json = serde_json::to_string(&env).unwrap();
        let back: EnvironmentSnapshot = serde_json::from_str(&json).unwrap();
        assert_eq!(back.working_dir.as_deref(), Some("/home/user/project"));
        assert_eq!(back.vcs_branch.as_deref(), Some("main"));
        assert_eq!(back.vcs_revision.as_deref(), Some("abc123"));
    }

    #[test]
    fn test_environment_snapshot_default() {
        let env = EnvironmentSnapshot::default();
        assert!(env.working_dir.is_none());
        assert!(env.vcs_branch.is_none());
        assert!(env.vcs_revision.is_none());
    }

    #[test]
    fn test_environment_snapshot_skip_none_fields() {
        let env = EnvironmentSnapshot {
            working_dir: Some("/tmp".into()),
            vcs_branch: None,
            vcs_revision: None,
        };
        let json = serde_json::to_string(&env).unwrap();
        assert!(!json.contains("vcs_branch"));
        assert!(!json.contains("vcs_revision"));
    }

    #[test]
    fn test_delegated_work_serde() {
        let dw = DelegatedWork {
            agent_id: "agent-123".into(),
            prompt: "Search for the bug".into(),
            turns: vec![],
            result: Some("Found the bug in auth.rs".into()),
        };
        let json = serde_json::to_string(&dw).unwrap();
        assert!(!json.contains("turns")); // empty vec skipped
        let back: DelegatedWork = serde_json::from_str(&json).unwrap();
        assert_eq!(back.agent_id, "agent-123");
        assert_eq!(back.result.as_deref(), Some("Found the bug in auth.rs"));
        assert!(back.turns.is_empty());
    }

    #[test]
    fn test_tool_category_serde() {
        let ti = ToolInvocation {
            id: "t1".into(),
            name: "Bash".into(),
            input: serde_json::json!({"command": "ls"}),
            result: None,
            category: Some(ToolCategory::Shell),
        };
        let json = serde_json::to_string(&ti).unwrap();
        assert!(json.contains("\"shell\""));
        let back: ToolInvocation = serde_json::from_str(&json).unwrap();
        assert_eq!(back.category, Some(ToolCategory::Shell));
    }

    #[test]
    fn test_tool_category_none_skipped() {
        let ti = ToolInvocation {
            id: "t1".into(),
            name: "CustomTool".into(),
            input: serde_json::json!({}),
            result: None,
            category: None,
        };
        let json = serde_json::to_string(&ti).unwrap();
        assert!(!json.contains("category"));
    }

    #[test]
    fn test_tool_category_missing_defaults_none() {
        // Old-format JSON without category should deserialize as None
        let json = r#"{"id":"t1","name":"Read","input":{},"result":null}"#;
        let ti: ToolInvocation = serde_json::from_str(json).unwrap();
        assert!(ti.category.is_none());
    }

    #[test]
    fn test_tool_category_all_variants_roundtrip() {
        let variants = vec![
            ToolCategory::FileRead,
            ToolCategory::FileWrite,
            ToolCategory::FileSearch,
            ToolCategory::Shell,
            ToolCategory::Network,
            ToolCategory::Delegation,
        ];
        for cat in variants {
            let json = serde_json::to_value(cat).unwrap();
            let back: ToolCategory = serde_json::from_value(json).unwrap();
            assert_eq!(back, cat);
        }
    }

    #[test]
    fn test_turn_with_environment_and_delegations() {
        let turn = Turn {
            id: "t1".into(),
            parent_id: None,
            role: Role::Assistant,
            timestamp: "2026-01-01T00:00:00Z".into(),
            text: "Delegating...".into(),
            thinking: None,
            tool_uses: vec![],
            model: None,
            stop_reason: None,
            token_usage: None,
            environment: Some(EnvironmentSnapshot {
                working_dir: Some("/project".into()),
                vcs_branch: Some("feat/auth".into()),
                vcs_revision: None,
            }),
            delegations: vec![DelegatedWork {
                agent_id: "sub-1".into(),
                prompt: "Find the bug".into(),
                turns: vec![],
                result: None,
            }],
            extra: HashMap::new(),
        };
        let json = serde_json::to_string(&turn).unwrap();
        let back: Turn = serde_json::from_str(&json).unwrap();
        assert_eq!(
            back.environment.as_ref().unwrap().vcs_branch.as_deref(),
            Some("feat/auth")
        );
        assert_eq!(back.delegations.len(), 1);
        assert_eq!(back.delegations[0].agent_id, "sub-1");
    }

    #[test]
    fn test_turn_without_new_fields_deserializes() {
        // Old-format Turn JSON without environment/delegations
        let json = r#"{"id":"t1","parent_id":null,"role":"User","timestamp":"2026-01-01T00:00:00Z","text":"hi","thinking":null,"tool_uses":[],"model":null,"stop_reason":null,"token_usage":null}"#;
        let turn: Turn = serde_json::from_str(json).unwrap();
        assert!(turn.environment.is_none());
        assert!(turn.delegations.is_empty());
    }

    #[test]
    fn test_conversation_view_new_fields_serde() {
        let view = ConversationView {
            id: "s1".into(),
            started_at: None,
            last_activity: None,
            turns: vec![],
            total_usage: Some(TokenUsage {
                input_tokens: Some(1000),
                output_tokens: Some(500),
                cache_read_tokens: Some(800),
                cache_write_tokens: None,
            }),
            provider_id: Some("claude-code".into()),
            files_changed: vec!["src/main.rs".into(), "src/lib.rs".into()],
            session_ids: vec![],
            events: vec![],
        };
        let json = serde_json::to_string(&view).unwrap();
        let back: ConversationView = serde_json::from_str(&json).unwrap();
        assert_eq!(back.provider_id.as_deref(), Some("claude-code"));
        assert_eq!(back.files_changed, vec!["src/main.rs", "src/lib.rs"]);
        assert_eq!(back.total_usage.as_ref().unwrap().input_tokens, Some(1000));
        assert_eq!(
            back.total_usage.as_ref().unwrap().cache_read_tokens,
            Some(800)
        );
    }

    #[test]
    fn test_conversation_view_old_format_deserializes() {
        // Old-format JSON without total_usage/provider_id/files_changed
        let json = r#"{"id":"s1","started_at":null,"last_activity":null,"turns":[]}"#;
        let view: ConversationView = serde_json::from_str(json).unwrap();
        assert!(view.total_usage.is_none());
        assert!(view.provider_id.is_none());
        assert!(view.files_changed.is_empty());
    }

    #[test]
    fn test_conversation_meta() {
        let meta = ConversationMeta {
            id: "sess-1".into(),
            started_at: None,
            last_activity: None,
            message_count: 5,
            file_path: Some("/tmp/test.jsonl".into()),
            predecessor: None,
            successor: None,
        };
        let json = serde_json::to_string(&meta).unwrap();
        let back: ConversationMeta = serde_json::from_str(&json).unwrap();
        assert_eq!(back.message_count, 5);
    }

    #[test]
    fn test_conversation_event_serde_roundtrip() {
        let event = ConversationEvent {
            id: "evt-1".into(),
            timestamp: "2026-01-01T00:00:00Z".into(),
            parent_id: Some("t1".into()),
            event_type: "attachment".into(),
            data: {
                let mut m = HashMap::new();
                m.insert("cwd".into(), serde_json::json!("/project"));
                m.insert("version".into(), serde_json::json!("1.0"));
                m
            },
        };
        let json = serde_json::to_string(&event).unwrap();
        let back: ConversationEvent = serde_json::from_str(&json).unwrap();
        assert_eq!(back.id, "evt-1");
        assert_eq!(back.event_type, "attachment");
        assert_eq!(back.parent_id.as_deref(), Some("t1"));
        assert_eq!(back.data["cwd"], serde_json::json!("/project"));
    }

    #[test]
    fn test_conversation_event_empty_data_omitted() {
        let event = ConversationEvent {
            id: "evt-2".into(),
            timestamp: "2026-01-01T00:00:00Z".into(),
            parent_id: None,
            event_type: "system".into(),
            data: HashMap::new(),
        };
        let json = serde_json::to_string(&event).unwrap();
        assert!(!json.contains("data"));
        assert!(!json.contains("parent_id"));
    }

    #[test]
    fn test_conversation_view_with_events_serde() {
        let view = ConversationView {
            id: "s1".into(),
            started_at: None,
            last_activity: None,
            turns: vec![],
            total_usage: None,
            provider_id: None,
            files_changed: vec![],
            session_ids: vec![],
            events: vec![ConversationEvent {
                id: "evt-1".into(),
                timestamp: "2026-01-01T00:00:00Z".into(),
                parent_id: None,
                event_type: "attachment".into(),
                data: HashMap::new(),
            }],
        };
        let json = serde_json::to_string(&view).unwrap();
        assert!(json.contains("events"));
        let back: ConversationView = serde_json::from_str(&json).unwrap();
        assert_eq!(back.events.len(), 1);
        assert_eq!(back.events[0].event_type, "attachment");
    }

    #[test]
    fn test_conversation_view_empty_events_omitted() {
        let view = ConversationView {
            id: "s1".into(),
            started_at: None,
            last_activity: None,
            turns: vec![],
            total_usage: None,
            provider_id: None,
            files_changed: vec![],
            session_ids: vec![],
            events: vec![],
        };
        let json = serde_json::to_string(&view).unwrap();
        assert!(!json.contains("events"));
    }

    #[test]
    fn test_conversation_view_old_format_no_events() {
        // Old-format JSON without events field should deserialize with empty vec
        let json = r#"{"id":"s1","started_at":null,"last_activity":null,"turns":[]}"#;
        let view: ConversationView = serde_json::from_str(json).unwrap();
        assert!(view.events.is_empty());
    }
}