treeship_core/session/
manifest.rs

1//! Enhanced session manifest for Session Receipt v1.
2
3use serde::{Deserialize, Serialize};
4
5/// Session lifecycle mode.
6#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
7#[serde(rename_all = "snake_case")]
8pub enum LifecycleMode {
9    /// User explicitly starts and ends the session.
10    Manual,
11    /// Auto-starts when registered agents begin activity in a watched workspace.
12    AutoWorkspace,
13    /// Day-level session with optional mission segments.
14    DailyRollup,
15}
16
17impl Default for LifecycleMode {
18    fn default() -> Self {
19        Self::AutoWorkspace
20    }
21}
22
23/// Summary of all participants in a session.
24#[derive(Debug, Clone, Default, Serialize, Deserialize)]
25pub struct Participants {
26    /// Instance ID of the root agent that initiated the session.
27    #[serde(skip_serializing_if = "Option::is_none")]
28    pub root_agent_instance_id: Option<String>,
29
30    /// Instance ID of the agent that produced the final output.
31    #[serde(skip_serializing_if = "Option::is_none")]
32    pub final_output_agent_instance_id: Option<String>,
33
34    /// Total number of distinct agents involved.
35    #[serde(default)]
36    pub total_agents: u32,
37
38    /// Number of sub-agents spawned during the session.
39    #[serde(default)]
40    pub spawned_subagents: u32,
41
42    /// Total number of handoffs between agents.
43    #[serde(default)]
44    pub handoffs: u32,
45
46    /// Deepest agent delegation chain depth.
47    #[serde(default)]
48    pub max_depth: u32,
49
50    /// Number of distinct hosts involved.
51    #[serde(default)]
52    pub hosts: u32,
53
54    /// Number of distinct tool runtimes involved.
55    #[serde(default)]
56    pub tool_runtimes: u32,
57}
58
59/// Information about a host involved in the session.
60#[derive(Debug, Clone, Serialize, Deserialize)]
61pub struct HostInfo {
62    pub host_id: String,
63    #[serde(skip_serializing_if = "Option::is_none")]
64    pub hostname: Option<String>,
65    #[serde(skip_serializing_if = "Option::is_none")]
66    pub os: Option<String>,
67    #[serde(skip_serializing_if = "Option::is_none")]
68    pub arch: Option<String>,
69}
70
71/// Information about a tool runtime involved in the session.
72#[derive(Debug, Clone, Serialize, Deserialize)]
73pub struct ToolInfo {
74    pub tool_id: String,
75    pub tool_name: String,
76    #[serde(skip_serializing_if = "Option::is_none")]
77    pub tool_runtime_id: Option<String>,
78    #[serde(default)]
79    pub invocation_count: u32,
80}
81
82/// Session status.
83#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
84#[serde(rename_all = "snake_case")]
85pub enum SessionStatus {
86    Active,
87    Completed,
88    Failed,
89    Abandoned,
90}
91
92impl Default for SessionStatus {
93    fn default() -> Self {
94        Self::Active
95    }
96}
97
98/// Enhanced session manifest for Session Receipt v1.
99///
100/// Backward-compatible with the original CLI SessionManifest:
101/// all new fields use `#[serde(default)]` so old session.json files
102/// deserialize without error.
103#[derive(Debug, Clone, Serialize, Deserialize)]
104pub struct SessionManifest {
105    pub session_id: String,
106
107    #[serde(skip_serializing_if = "Option::is_none")]
108    pub name: Option<String>,
109
110    pub actor: String,
111
112    pub started_at: String,
113
114    #[serde(default)]
115    pub started_at_ms: u64,
116
117    #[serde(default)]
118    pub artifact_count: u64,
119
120    #[serde(skip_serializing_if = "Option::is_none")]
121    pub root_artifact_id: Option<String>,
122
123    // --- v1 fields below ---
124
125    #[serde(default)]
126    pub mode: LifecycleMode,
127
128    #[serde(default)]
129    pub status: SessionStatus,
130
131    #[serde(skip_serializing_if = "Option::is_none")]
132    pub workspace_id: Option<String>,
133
134    #[serde(skip_serializing_if = "Option::is_none")]
135    pub mission_id: Option<String>,
136
137    #[serde(skip_serializing_if = "Option::is_none")]
138    pub closed_at: Option<String>,
139
140    #[serde(skip_serializing_if = "Option::is_none")]
141    pub close_artifact_id: Option<String>,
142
143    #[serde(skip_serializing_if = "Option::is_none")]
144    pub summary: Option<String>,
145
146    #[serde(default)]
147    pub participants: Participants,
148
149    #[serde(default, skip_serializing_if = "Vec::is_empty")]
150    pub hosts: Vec<HostInfo>,
151
152    #[serde(default, skip_serializing_if = "Vec::is_empty")]
153    pub tools: Vec<ToolInfo>,
154}
155
156impl SessionManifest {
157    /// Create a new manifest with required fields; v1 fields default.
158    pub fn new(session_id: String, actor: String, started_at: String, started_at_ms: u64) -> Self {
159        Self {
160            session_id,
161            name: None,
162            actor,
163            started_at,
164            started_at_ms,
165            artifact_count: 0,
166            root_artifact_id: None,
167            mode: LifecycleMode::default(),
168            status: SessionStatus::Active,
169            workspace_id: None,
170            mission_id: None,
171            closed_at: None,
172            close_artifact_id: None,
173            summary: None,
174            participants: Participants::default(),
175            hosts: Vec::new(),
176            tools: Vec::new(),
177        }
178    }
179}
180
181#[cfg(test)]
182mod tests {
183    use super::*;
184
185    #[test]
186    fn deserialize_legacy_manifest() {
187        // Old format without v1 fields should still deserialize
188        let json = r#"{
189            "session_id": "ssn_abc123",
190            "name": "test",
191            "actor": "ship://local",
192            "started_at": "2026-04-05T08:00:00Z",
193            "started_at_ms": 1743843600000,
194            "artifact_count": 5,
195            "root_artifact_id": "art_deadbeef"
196        }"#;
197        let m: SessionManifest = serde_json::from_str(json).unwrap();
198        assert_eq!(m.session_id, "ssn_abc123");
199        assert_eq!(m.mode, LifecycleMode::AutoWorkspace);
200        assert_eq!(m.status, SessionStatus::Active);
201        assert_eq!(m.participants.total_agents, 0);
202    }
203
204    #[test]
205    fn roundtrip_full_manifest() {
206        let m = SessionManifest {
207            session_id: "ssn_001".into(),
208            name: Some("daily dev".into()),
209            actor: "agent://claude".into(),
210            started_at: "2026-04-05T08:00:00Z".into(),
211            started_at_ms: 1743843600000,
212            artifact_count: 12,
213            root_artifact_id: Some("art_root".into()),
214            mode: LifecycleMode::Manual,
215            status: SessionStatus::Completed,
216            workspace_id: Some("ws_abc".into()),
217            mission_id: None,
218            closed_at: Some("2026-04-05T12:00:00Z".into()),
219            close_artifact_id: Some("art_close".into()),
220            summary: Some("Fixed auth bug".into()),
221            participants: Participants {
222                root_agent_instance_id: Some("ai_root_1".into()),
223                final_output_agent_instance_id: Some("ai_review_2".into()),
224                total_agents: 6,
225                spawned_subagents: 4,
226                handoffs: 7,
227                max_depth: 3,
228                hosts: 2,
229                tool_runtimes: 5,
230            },
231            hosts: vec![HostInfo {
232                host_id: "host_1".into(),
233                hostname: Some("macbook".into()),
234                os: Some("darwin".into()),
235                arch: Some("arm64".into()),
236            }],
237            tools: vec![ToolInfo {
238                tool_id: "tool_1".into(),
239                tool_name: "claude-code".into(),
240                tool_runtime_id: Some("rt_cc1".into()),
241                invocation_count: 42,
242            }],
243        };
244        let json = serde_json::to_string_pretty(&m).unwrap();
245        let m2: SessionManifest = serde_json::from_str(&json).unwrap();
246        assert_eq!(m2.session_id, "ssn_001");
247        assert_eq!(m2.participants.total_agents, 6);
248        assert_eq!(m2.hosts.len(), 1);
249    }
250}
treeship_core/session/manifest.rs

treeship_core/session/
manifest.rs
