handoff-mcp-server 0.4.0 → 0.6.1

package/src/mcp/tools.rs

@@ -35,6 +35,10 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     "project_dir": {
                         "type": "string",
                         "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "session_id": {
+                        "type": "string",
+                        "description": "Session ID to activate and load. If omitted, activates all open sessions and returns the latest."
                     }
                 }
             }),
@@ -53,16 +57,21 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                         "type": "string",
                         "description": "One-line summary of this session"
                     },
+                    "close_session_id": {
+                        "type": "string",
+                        "description": "Session ID to close. If omitted, all active and open sessions are closed (default behavior)."
+                    },
                     "decisions": {
                         "type": "array",
                         "description": "Decisions made during this session",
                         "items": {
                             "type": "object",
                             "properties": {
-                                "decision": { "type": "string" },
-                                "reason": { "type": "string" },
+                                "decision": { "type": "string", "description": "What was decided" },
+                                "reason": { "type": "string", "description": "Why this decision was made" },
                                 "confidence": {
                                     "type": "string",
+                                    "description": "confirmed = verified by testing/evidence; estimated = reasoned but not verified; unverified = hypothesis needing validation",
                                     "enum": ["confirmed", "estimated", "unverified"]
                                 }
                             },
@@ -71,17 +80,20 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     },
                     "blockers": {
                         "type": "array",
+                        "description": "Issues preventing progress. The next session should address these before starting new work.",
                         "items": { "type": "string" }
                     },
                     "checklist": {
                         "type": "array",
+                        "description": "Verification items for the next session or user. Mark completed items as checked:true before saving.",
                         "items": {
                             "type": "object",
                             "properties": {
-                                "item": { "type": "string" },
-                                "checked": { "type": "boolean" },
+                                "item": { "type": "string", "description": "What to verify or confirm" },
+                                "checked": { "type": "boolean", "description": "true if already verified, false if pending" },
                                 "owner": {
                                     "type": "string",
+                                    "description": "user = requires human action; ai = the next AI session should handle this",
                                     "enum": ["user", "ai"]
                                 }
                             },
@@ -90,12 +102,14 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     },
                     "handoff_notes": {
                         "type": "array",
+                        "description": "Notes for the next session. Include at least one 'suggestion' with a concrete next action.",
                         "items": {
                             "type": "object",
                             "properties": {
-                                "note": { "type": "string" },
+                                "note": { "type": "string", "description": "The note content. For suggestions: state what is ALREADY DONE, then describe the concrete next action." },
                                 "category": {
                                     "type": "string",
+                                    "description": "caution = risks/rules the next session must respect; context = background info for decisions; suggestion = concrete next action the next session should execute first (at least one required)",
                                     "enum": ["caution", "context", "suggestion"]
                                 }
                             },
@@ -104,28 +118,31 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     },
                     "references": {
                         "type": "array",
+                        "description": "Links to related docs, issues, MRs, or external resources for reference (not active work files — use context_pointers for those).",
                         "items": {
                             "type": "object",
                             "properties": {
-                                "label": { "type": "string" },
-                                "uri": { "type": "string" },
+                                "label": { "type": "string", "description": "Human-readable label for this reference" },
+                                "uri": { "type": "string", "description": "Path, URL, or identifier" },
                                 "type": {
                                     "type": "string",
+                                    "description": "file = project file; issue = issue tracker; mr = merge/pull request; wiki = wiki page; doc = design document; url = external URL",
                                     "enum": ["file", "issue", "mr", "wiki", "doc", "url"]
                                 },
-                                "notes": { "type": "string" }
+                                "notes": { "type": "string", "description": "Additional context (e.g. 'see section 3 for root cause analysis')" }
                             },
                             "required": ["label", "uri"]
                         }
                     },
                     "context_pointers": {
                         "type": "array",
+                        "description": "Files the next session should open first to resume work. Point to files that NEED WORK, not completed files. For completed files, use a 'context' handoff_note instead.",
                         "items": {
                             "type": "object",
                             "properties": {
-                                "path": { "type": "string" },
-                                "reason": { "type": "string" },
-                                "lines": { "type": "string" }
+                                "path": { "type": "string", "description": "File path relative to project root" },
+                                "reason": { "type": "string", "description": "Why the next session should read this (e.g. 'resume implementation here', 'needs review')" },
+                                "lines": { "type": "string", "description": "Line range to focus on (e.g. '42-78')" }
                             },
                             "required": ["path"]
                         }
@@ -366,13 +383,15 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                             "summary": { "type": "string", "description": "One-line summary (required)" },
                             "decisions": {
                                 "type": "array",
+                                "description": "Decisions made during this session",
                                 "items": {
                                     "type": "object",
                                     "properties": {
-                                        "decision": { "type": "string" },
-                                        "reason": { "type": "string" },
+                                        "decision": { "type": "string", "description": "What was decided" },
+                                        "reason": { "type": "string", "description": "Why this decision was made" },
                                         "confidence": {
                                             "type": "string",
+                                            "description": "confirmed = verified; estimated = reasoned but not verified; unverified = hypothesis",
                                             "enum": ["confirmed", "estimated", "unverified"]
                                         }
                                     },
@@ -381,52 +400,57 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                             },
                             "blockers": {
                                 "type": "array",
+                                "description": "Issues preventing progress",
                                 "items": { "type": "string" }
                             },
                             "checklist": {
                                 "type": "array",
+                                "description": "Verification items for the next session or user",
                                 "items": {
                                     "type": "object",
                                     "properties": {
-                                        "item": { "type": "string" },
-                                        "checked": { "type": "boolean" },
-                                        "owner": { "type": "string", "enum": ["user", "ai"] }
+                                        "item": { "type": "string", "description": "What to verify" },
+                                        "checked": { "type": "boolean", "description": "true if verified, false if pending" },
+                                        "owner": { "type": "string", "description": "user = human action; ai = next AI session", "enum": ["user", "ai"] }
                                     },
                                     "required": ["item"]
                                 }
                             },
                             "handoff_notes": {
                                 "type": "array",
+                                "description": "Notes for the next session. Include at least one 'suggestion' with a concrete next action.",
                                 "items": {
                                     "type": "object",
                                     "properties": {
-                                        "note": { "type": "string" },
-                                        "category": { "type": "string", "enum": ["caution", "context", "suggestion"] }
+                                        "note": { "type": "string", "description": "The note content. For suggestions: state what is done, then the next action." },
+                                        "category": { "type": "string", "description": "caution = risks/rules; context = background; suggestion = concrete next action (at least one required)", "enum": ["caution", "context", "suggestion"] }
                                     },
                                     "required": ["note"]
                                 }
                             },
                             "references": {
                                 "type": "array",
+                                "description": "Links to related docs, issues, MRs (not active work files)",
                                 "items": {
                                     "type": "object",
                                     "properties": {
-                                        "label": { "type": "string" },
-                                        "uri": { "type": "string" },
-                                        "type": { "type": "string", "enum": ["file", "issue", "mr", "wiki", "doc", "url"] },
-                                        "notes": { "type": "string" }
+                                        "label": { "type": "string", "description": "Human-readable label" },
+                                        "uri": { "type": "string", "description": "Path, URL, or identifier" },
+                                        "type": { "type": "string", "description": "file/issue/mr/wiki/doc/url", "enum": ["file", "issue", "mr", "wiki", "doc", "url"] },
+                                        "notes": { "type": "string", "description": "Additional context" }
                                     },
                                     "required": ["label", "uri"]
                                 }
                             },
                             "context_pointers": {
                                 "type": "array",
+                                "description": "Files the next session should open first to resume work (not completed files)",
                                 "items": {
                                     "type": "object",
                                     "properties": {
-                                        "path": { "type": "string" },
-                                        "reason": { "type": "string" },
-                                        "lines": { "type": "string" }
+                                        "path": { "type": "string", "description": "File path relative to project root" },
+                                        "reason": { "type": "string", "description": "Why to read this file" },
+                                        "lines": { "type": "string", "description": "Line range (e.g. '42-78')" }
                                     },
                                     "required": ["path"]
                                 }

package/src/storage/sessions.rs

@@ -7,6 +7,8 @@ use serde_json::Value;
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SessionData {
     pub version: u32,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub id: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub ended_at: Option<String>,
     pub summary: String,
@@ -32,6 +34,11 @@ pub struct SessionData {
     pub environment: Option<Value>,
 }
 
+pub fn generate_session_id() -> String {
+    let now = chrono::Utc::now();
+    format!("s-{}", now.format("%Y%m%d-%H%M%S-%6f"))
+}
+
 pub fn generate_session_filename(summary: &str, timestamp: &str) -> String {
     let slug = summary_to_slug(summary);
     format!("{timestamp}-{slug}")
@@ -72,53 +79,57 @@ fn summary_to_slug(summary: &str) -> String {
     }
 }
 
-pub fn write_active_session(sessions_dir: &Path, data: &SessionData) -> Result<PathBuf> {
+fn compact_timestamp(data: &SessionData) -> String {
     let timestamp = data.ended_at.as_deref().unwrap_or("00000000-000000");
     let ts_compact = timestamp
         .replace(['-', ':'], "")
         .replace('T', "-")
         .replace('Z', "");
-    let ts_part = if ts_compact.len() >= 15 {
-        &ts_compact[..15]
+    if ts_compact.len() >= 15 {
+        ts_compact[..15].to_string()
     } else {
-        &ts_compact
-    };
-
-    let base = generate_session_filename(&data.summary, ts_part);
-    let filename = format!("{base}.active.json");
-    let path = sessions_dir.join(&filename);
-
-    let content = serde_json::to_string_pretty(data).context("Failed to serialize session")?;
-    std::fs::write(&path, content)
-        .with_context(|| format!("Failed to write session: {}", path.display()))?;
-
-    Ok(path)
+        ts_compact
+    }
 }
 
-pub fn close_active_sessions(sessions_dir: &Path) -> Result<Vec<PathBuf>> {
-    let mut closed = Vec::new();
+fn synthesize_id_from_filename(filename: &str) -> String {
+    // Old format: YYYYMMDD-HHMMSS-slug.status.json
+    // Extract timestamp part and create s-YYYYMMDD-HHMMSS-000000
+    let base = filename
+        .rsplit_once('.')
+        .and_then(|(rest, _)| rest.rsplit_once('.'))
+        .map(|(rest, _)| rest)
+        .unwrap_or(filename);
 
-    if !sessions_dir.exists() {
-        return Ok(closed);
+    if base.len() >= 15 {
+        let ts = &base[..15]; // YYYYMMDD-HHMMSS
+        format!("s-{ts}-000000")
+    } else {
+        format!("s-{base}-000000")
     }
+}
 
-    for entry in std::fs::read_dir(sessions_dir)? {
-        let entry = entry?;
-        let name = entry.file_name().to_string_lossy().to_string();
-        if name.ends_with(".active.json") {
-            let new_name = name.replace(".active.json", ".closed.json");
-            let new_path = sessions_dir.join(&new_name);
-            std::fs::rename(entry.path(), &new_path)
-                .with_context(|| format!("Failed to close session: {}", entry.path().display()))?;
-            closed.push(new_path);
-        }
+pub fn write_open_session(sessions_dir: &Path, data: &SessionData) -> Result<PathBuf> {
+    let mut data = data.clone();
+    if data.id.is_none() {
+        data.id = Some(generate_session_id());
     }
 
-    Ok(closed)
+    let ts_part = compact_timestamp(&data);
+    let base = generate_session_filename(&data.summary, &ts_part);
+    let filename = format!("{base}.open.json");
+    let path = sessions_dir.join(&filename);
+
+    let content = serde_json::to_string_pretty(&data).context("Failed to serialize session")?;
+    std::fs::write(&path, content)
+        .with_context(|| format!("Failed to write session: {}", path.display()))?;
+
+    Ok(path)
 }
 
-pub fn read_active_sessions(sessions_dir: &Path) -> Result<Vec<SessionData>> {
+pub fn read_sessions_by_status(sessions_dir: &Path, status: &str) -> Result<Vec<SessionData>> {
     let mut sessions = Vec::new();
+    let suffix = format!(".{status}.json");
 
     if !sessions_dir.exists() {
         return Ok(sessions);
@@ -131,11 +142,14 @@ pub fn read_active_sessions(sessions_dir: &Path) -> Result<Vec<SessionData>> {
 
     for entry in entries {
         let name = entry.file_name().to_string_lossy().to_string();
-        if name.ends_with(".active.json") {
+        if name.ends_with(&suffix) {
             let content = std::fs::read_to_string(entry.path())
                 .with_context(|| format!("Failed to read session: {}", entry.path().display()))?;
-            let data: SessionData = serde_json::from_str(&content)
+            let mut data: SessionData = serde_json::from_str(&content)
                 .with_context(|| format!("Failed to parse session: {}", entry.path().display()))?;
+            if data.id.is_none() {
+                data.id = Some(synthesize_id_from_filename(&name));
+            }
             sessions.push(data);
         }
     }
@@ -143,6 +157,114 @@ pub fn read_active_sessions(sessions_dir: &Path) -> Result<Vec<SessionData>> {
     Ok(sessions)
 }
 
+pub fn read_open_sessions(sessions_dir: &Path) -> Result<Vec<SessionData>> {
+    read_sessions_by_status(sessions_dir, "open")
+}
+
+pub fn read_active_sessions(sessions_dir: &Path) -> Result<Vec<SessionData>> {
+    read_sessions_by_status(sessions_dir, "active")
+}
+
+fn transition_sessions(sessions_dir: &Path, from: &str, to: &str) -> Result<Vec<PathBuf>> {
+    let mut transitioned = Vec::new();
+    let from_suffix = format!(".{from}.json");
+    let to_suffix = format!(".{to}.json");
+
+    if !sessions_dir.exists() {
+        return Ok(transitioned);
+    }
+
+    for entry in std::fs::read_dir(sessions_dir)? {
+        let entry = entry?;
+        let name = entry.file_name().to_string_lossy().to_string();
+        if name.ends_with(&from_suffix) {
+            let new_name = name.replace(&from_suffix, &to_suffix);
+            let new_path = sessions_dir.join(&new_name);
+            std::fs::rename(entry.path(), &new_path).with_context(|| {
+                format!(
+                    "Failed to transition session {from}->{to}: {}",
+                    entry.path().display()
+                )
+            })?;
+            transitioned.push(new_path);
+        }
+    }
+
+    Ok(transitioned)
+}
+
+fn transition_session_by_id(
+    sessions_dir: &Path,
+    session_id: &str,
+    from: &str,
+    to: &str,
+) -> Result<Option<PathBuf>> {
+    let from_suffix = format!(".{from}.json");
+    let to_suffix = format!(".{to}.json");
+
+    if !sessions_dir.exists() {
+        return Ok(None);
+    }
+
+    for entry in std::fs::read_dir(sessions_dir)? {
+        let entry = entry?;
+        let name = entry.file_name().to_string_lossy().to_string();
+        if !name.ends_with(&from_suffix) {
+            continue;
+        }
+
+        let content = std::fs::read_to_string(entry.path())
+            .with_context(|| format!("Failed to read session: {}", entry.path().display()))?;
+        let data: SessionData = serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse session: {}", entry.path().display()))?;
+
+        let file_id = data.id.as_deref().unwrap_or("").to_string();
+        let synthesized = if file_id.is_empty() {
+            synthesize_id_from_filename(&name)
+        } else {
+            file_id
+        };
+
+        if synthesized == session_id {
+            let new_name = name.replace(&from_suffix, &to_suffix);
+            let new_path = sessions_dir.join(&new_name);
+            std::fs::rename(entry.path(), &new_path).with_context(|| {
+                format!(
+                    "Failed to transition session {from}->{to}: {}",
+                    entry.path().display()
+                )
+            })?;
+            return Ok(Some(new_path));
+        }
+    }
+
+    Ok(None)
+}
+
+pub fn activate_open_sessions(sessions_dir: &Path) -> Result<Vec<PathBuf>> {
+    transition_sessions(sessions_dir, "open", "active")
+}
+
+pub fn activate_session_by_id(sessions_dir: &Path, session_id: &str) -> Result<Option<PathBuf>> {
+    transition_session_by_id(sessions_dir, session_id, "open", "active")
+}
+
+pub fn close_active_sessions(sessions_dir: &Path) -> Result<Vec<PathBuf>> {
+    transition_sessions(sessions_dir, "active", "closed")
+}
+
+pub fn close_open_sessions(sessions_dir: &Path) -> Result<Vec<PathBuf>> {
+    transition_sessions(sessions_dir, "open", "closed")
+}
+
+pub fn close_session_by_id(sessions_dir: &Path, session_id: &str) -> Result<Option<PathBuf>> {
+    // Try active first, then open
+    if let Some(path) = transition_session_by_id(sessions_dir, session_id, "active", "closed")? {
+        return Ok(Some(path));
+    }
+    transition_session_by_id(sessions_dir, session_id, "open", "closed")
+}
+
 pub fn enforce_history_limit(sessions_dir: &Path, limit: u32) -> Result<u32> {
     if !sessions_dir.exists() {
         return Ok(0);
@@ -172,3 +294,9 @@ pub fn enforce_history_limit(sessions_dir: &Path, limit: u32) -> Result<u32> {
 
     Ok(removed)
 }
+
+// Backward-compatible aliases for tests and migration
+#[doc(hidden)]
+pub fn write_active_session(sessions_dir: &Path, data: &SessionData) -> Result<PathBuf> {
+    write_open_session(sessions_dir, data)
+}