motosan_agent_loop/session/

entry.rs

//! Session entry — the unit of persistent storage.
//!
//! The store operates on `SessionEntry`, not `Message` directly. An entry
//! is either a `Message` (LLM-facing conversation content) or a `Custom`
//! entry (app-defined sidecar data that, by default, the LLM never sees).

use serde::{Deserialize, Serialize};

use crate::message::Message;

/// Opaque identifier for a persisted entry. Generated by the store on
/// append.
pub type EntryId = String;

/// A single persisted entry in a session log.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum SessionEntry {
    /// A conversation message visible to the LLM.
    Message {
        #[serde(flatten)]
        message: Message,
    },
    /// App-defined sidecar entry.
    Custom {
        /// App-defined namespace.
        kind: String,
        /// Opaque JSON payload.
        payload: serde_json::Value,
    },
}

impl SessionEntry {
    /// Construct a message entry.
    pub fn message(message: Message) -> Self {
        Self::Message { message }
    }

    /// Construct a custom entry.
    pub fn custom(kind: impl Into<String>, payload: serde_json::Value) -> Self {
        Self::Custom {
            kind: kind.into(),
            payload,
        }
    }

    /// Borrow the inner `Message`, if this entry is a message.
    pub fn as_message(&self) -> Option<&Message> {
        match self {
            Self::Message { message } => Some(message),
            Self::Custom { .. } => None,
        }
    }

    /// The `kind` of a custom entry, or `None` for message entries.
    pub fn custom_kind(&self) -> Option<&str> {
        match self {
            Self::Custom { kind, .. } => Some(kind.as_str()),
            Self::Message { .. } => None,
        }
    }
}

/// A persisted entry together with its log-position metadata.
///
/// This is the record `SessionStore::load_entries` yields and the unit the
/// projection consumes. `parent_id` describes *log position* — "the entry
/// this one continues from" — not message content, which is why it lives on
/// this record and not inside [`SessionEntry`].
///
/// - `parent_id == None` ⇒ continues the positional predecessor (the entry
///   on the immediately preceding log line). `None` at line 0 means root.
/// - `parent_id == Some(id)` ⇒ continues entry `id`, anywhere earlier in the
///   log. This is a **branch point**.
///
/// Invariant: only branch points carry `Some`. Every other entry's parent is
/// its positional predecessor, hence `None`. A never-branched session has
/// `None` on every line, so `parent_id` is omitted from the serialized form
/// (`skip_serializing_if`) and the file is byte-identical to a pre-0.20 log.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StoredEntry {
    /// Opaque id of this entry.
    pub id: EntryId,
    /// The entry this one continues from. See the type docs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub parent_id: Option<EntryId>,
    /// The persisted payload.
    pub entry: SessionEntry,
}

impl StoredEntry {
    /// A linear entry — `parent_id` is `None` (continues the previous line).
    pub fn new(id: EntryId, entry: SessionEntry) -> Self {
        Self {
            id,
            parent_id: None,
            entry,
        }
    }

    /// An entry with an explicit parent. Pass `Some(..)` to create a branch
    /// point; `None` is equivalent to [`StoredEntry::new`].
    pub fn with_parent(id: EntryId, parent_id: Option<EntryId>, entry: SessionEntry) -> Self {
        Self {
            id,
            parent_id,
            entry,
        }
    }
}

/// Generate a new `EntryId`.
pub fn new_entry_id() -> EntryId {
    ulid::Ulid::new().to_string()
}

/// Generate a deterministic `EntryId` from a positional index and content.
///
/// Used for legacy (pre-0.15) session entries that were stored without
/// explicit IDs.  The same (index, content) pair always produces the same
/// ID, which is critical for compaction markers that reference entry IDs
/// across restarts.
pub fn deterministic_entry_id(index: usize, content: &str) -> EntryId {
    use siphasher::sip::SipHasher13;
    use std::hash::{Hash, Hasher};

    let mut hasher = SipHasher13::new();
    index.hash(&mut hasher);
    content.hash(&mut hasher);
    format!("legacy-{index:08x}-{:016x}", hasher.finish())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::message::Message;
    use serde_json::json;

    #[test]
    fn message_entry_round_trips_json() {
        let entry = SessionEntry::message(Message::user("hi"));
        let s = serde_json::to_string(&entry).unwrap();
        let parsed: SessionEntry = serde_json::from_str(&s).unwrap();
        assert!(matches!(parsed, SessionEntry::Message { .. }));
        assert_eq!(parsed.as_message().unwrap().text(), "hi");
    }

    #[test]
    fn session_entry_wrapping_tagged_message_has_both_type_and_role() {
        let entry = SessionEntry::message(Message::user("hi"));
        let s = serde_json::to_string(&entry).unwrap();
        assert!(s.contains("\"type\":\"message\""), "entry tag missing: {s}");
        assert!(s.contains("\"role\":\"user\""), "message tag missing: {s}");
        let back: SessionEntry = serde_json::from_str(&s).unwrap();
        assert!(matches!(back, SessionEntry::Message { .. }));
        assert_eq!(back.as_message().unwrap().text(), "hi");
    }

    #[test]
    fn custom_entry_round_trips_json() {
        let entry = SessionEntry::custom(
            "compaction",
            json!({ "summary": "earlier stuff", "first_kept_entry_id": "01ABC" }),
        );
        let s = serde_json::to_string(&entry).unwrap();
        let parsed: SessionEntry = serde_json::from_str(&s).unwrap();
        assert_eq!(parsed.custom_kind(), Some("compaction"));
        match parsed {
            SessionEntry::Custom { payload, .. } => {
                assert_eq!(payload["summary"], "earlier stuff");
            }
            _ => panic!("expected Custom"),
        }
    }

    #[test]
    fn message_entry_does_not_report_custom_kind() {
        let e = SessionEntry::message(Message::assistant("ok"));
        assert!(e.custom_kind().is_none());
    }

    #[test]
    fn custom_entry_does_not_report_message() {
        let e = SessionEntry::custom("foo", json!({}));
        assert!(e.as_message().is_none());
    }

    #[test]
    fn new_entry_id_is_ulid_like() {
        let a = new_entry_id();
        let b = new_entry_id();
        assert_ne!(a, b);
        assert_eq!(a.len(), 26);
        assert_eq!(b.len(), 26);
    }

    #[test]
    fn deterministic_entry_id_is_stable() {
        assert_eq!(
            deterministic_entry_id(1, "{\"role\":\"User\",\"content\":\"hello\"}"),
            "legacy-00000001-2dccd4ce84ec3aec"
        );
    }

    #[test]
    fn stored_entry_omits_parent_id_when_none() {
        let se = StoredEntry::new(
            "01ABC".to_string(),
            SessionEntry::message(Message::user("hi")),
        );
        let json = serde_json::to_string(&se).unwrap();
        assert!(
            !json.contains("parent_id"),
            "a flat entry must not serialize parent_id: {json}"
        );
        let back: StoredEntry = serde_json::from_str(&json).unwrap();
        assert_eq!(back.id, "01ABC");
        assert!(back.parent_id.is_none());
        assert_eq!(back.entry.as_message().unwrap().text(), "hi");
    }

    #[test]
    fn stored_entry_round_trips_parent_id() {
        let se = StoredEntry::with_parent(
            "child".to_string(),
            Some("parent".to_string()),
            SessionEntry::message(Message::user("hi")),
        );
        let json = serde_json::to_string(&se).unwrap();
        assert!(json.contains("\"parent_id\":\"parent\""), "{json}");
        let back: StoredEntry = serde_json::from_str(&json).unwrap();
        assert_eq!(back.parent_id.as_deref(), Some("parent"));
    }

    #[test]
    fn stored_entry_deserializes_legacy_line_without_parent_id() {
        // A pre-0.20 entry line carried only `id` + `entry`. It must load
        // with parent_id == None (a pure linear chain).
        let entry = SessionEntry::message(Message::user("hi"));
        let line = serde_json::json!({
            "id": "x",
            "entry": serde_json::to_value(&entry).unwrap(),
        })
        .to_string();
        let se: StoredEntry = serde_json::from_str(&line).unwrap();
        assert!(se.parent_id.is_none());
        assert_eq!(se.entry.as_message().unwrap().text(), "hi");
    }
}