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    #[serde(default)]
125    pub mode: LifecycleMode,
126
127    #[serde(default)]
128    pub status: SessionStatus,
129
130    #[serde(skip_serializing_if = "Option::is_none")]
131    pub workspace_id: Option<String>,
132
133    #[serde(skip_serializing_if = "Option::is_none")]
134    pub mission_id: Option<String>,
135
136    #[serde(skip_serializing_if = "Option::is_none")]
137    pub closed_at: Option<String>,
138
139    #[serde(skip_serializing_if = "Option::is_none")]
140    pub close_artifact_id: Option<String>,
141
142    #[serde(skip_serializing_if = "Option::is_none")]
143    pub summary: Option<String>,
144
145    #[serde(default)]
146    pub participants: Participants,
147
148    #[serde(default, skip_serializing_if = "Vec::is_empty")]
149    pub hosts: Vec<HostInfo>,
150
151    #[serde(default, skip_serializing_if = "Vec::is_empty")]
152    pub tools: Vec<ToolInfo>,
153
154    /// Tools declared as authorized for this session (from declaration.json).
155    #[serde(default, skip_serializing_if = "Vec::is_empty")]
156    pub authorized_tools: Vec<String>,
157
158    /// Git HEAD SHA captured at session start, when the project is a
159    /// git repo. Used by session::close to compute committed-during-
160    /// session changes via `git diff <sha>..HEAD` for the
161    /// reconciliation pass. Absent for non-git projects or for
162    /// sessions started before this field existed.
163    #[serde(default, skip_serializing_if = "Option::is_none")]
164    pub start_commit_sha: Option<String>,
165}
166
167impl SessionManifest {
168    /// Create a new manifest with required fields; v1 fields default.
169    pub fn new(session_id: String, actor: String, started_at: String, started_at_ms: u64) -> Self {
170        Self {
171            session_id,
172            name: None,
173            actor,
174            started_at,
175            started_at_ms,
176            artifact_count: 0,
177            root_artifact_id: None,
178            mode: LifecycleMode::default(),
179            status: SessionStatus::Active,
180            workspace_id: None,
181            mission_id: None,
182            closed_at: None,
183            close_artifact_id: None,
184            summary: None,
185            participants: Participants::default(),
186            hosts: Vec::new(),
187            tools: Vec::new(),
188            authorized_tools: Vec::new(),
189            start_commit_sha: None,
190        }
191    }
192}
193
194#[cfg(test)]
195mod tests {
196    use super::*;
197
198    #[test]
199    fn deserialize_legacy_manifest() {
200        // Old format without v1 fields should still deserialize
201        let json = r#"{
202            "session_id": "ssn_abc123",
203            "name": "test",
204            "actor": "ship://local",
205            "started_at": "2026-04-05T08:00:00Z",
206            "started_at_ms": 1743843600000,
207            "artifact_count": 5,
208            "root_artifact_id": "art_deadbeef"
209        }"#;
210        let m: SessionManifest = serde_json::from_str(json).unwrap();
211        assert_eq!(m.session_id, "ssn_abc123");
212        assert_eq!(m.mode, LifecycleMode::AutoWorkspace);
213        assert_eq!(m.status, SessionStatus::Active);
214        assert_eq!(m.participants.total_agents, 0);
215    }
216
217    #[test]
218    fn roundtrip_full_manifest() {
219        let m = SessionManifest {
220            session_id: "ssn_001".into(),
221            name: Some("daily dev".into()),
222            actor: "agent://claude".into(),
223            started_at: "2026-04-05T08:00:00Z".into(),
224            started_at_ms: 1743843600000,
225            artifact_count: 12,
226            root_artifact_id: Some("art_root".into()),
227            mode: LifecycleMode::Manual,
228            status: SessionStatus::Completed,
229            workspace_id: Some("ws_abc".into()),
230            mission_id: None,
231            closed_at: Some("2026-04-05T12:00:00Z".into()),
232            close_artifact_id: Some("art_close".into()),
233            summary: Some("Fixed auth bug".into()),
234            participants: Participants {
235                root_agent_instance_id: Some("ai_root_1".into()),
236                final_output_agent_instance_id: Some("ai_review_2".into()),
237                total_agents: 6,
238                spawned_subagents: 4,
239                handoffs: 7,
240                max_depth: 3,
241                hosts: 2,
242                tool_runtimes: 5,
243            },
244            hosts: vec![HostInfo {
245                host_id: "host_1".into(),
246                hostname: Some("macbook".into()),
247                os: Some("darwin".into()),
248                arch: Some("arm64".into()),
249            }],
250            tools: vec![ToolInfo {
251                tool_id: "tool_1".into(),
252                tool_name: "claude-code".into(),
253                tool_runtime_id: Some("rt_cc1".into()),
254                invocation_count: 42,
255            }],
256            authorized_tools: vec!["read_file".into(), "write_file".into()],
257            start_commit_sha: Some("abc1234567890abcdef1234567890abcdef12345".into()),
258        };
259        let json = serde_json::to_string_pretty(&m).unwrap();
260        let m2: SessionManifest = serde_json::from_str(&json).unwrap();
261        assert_eq!(m2.session_id, "ssn_001");
262        assert_eq!(m2.participants.total_agents, 6);
263        assert_eq!(m2.hosts.len(), 1);
264    }
265}
treeship_core/session/manifest.rs

treeship_core/session/
manifest.rs
