handoff-mcp-server 0.8.1 → 0.11.0

package/src/mcp/handlers/milestones.rs

@@ -0,0 +1,102 @@
+//! Milestone CRUD over the `[milestones.<name>]` config.toml section.
+//! Mirrors the VSCode extension's addMilestone/updateMilestone/removeMilestone.
+
+use anyhow::Result;
+use serde_json::{json, Value};
+use toml_edit::{Item, Table};
+
+use super::config_crud::{
+    config_path, ensure_subtable, ensure_table, load_doc, require_str, save_doc, set_opt_str,
+};
+
+/// handoff_list_milestones — return every `[milestones.*]` entry.
+pub fn handle_list(arguments: &Value) -> Result<String> {
+    let path = config_path(arguments)?;
+    let doc = load_doc(&path)?;
+
+    let mut out = serde_json::Map::new();
+    if let Some(table) = doc.get("milestones").and_then(|v| v.as_table()) {
+        for (name, item) in table.iter() {
+            let sub = match item.as_table() {
+                Some(t) => t,
+                None => continue,
+            };
+            out.insert(
+                name.to_string(),
+                json!({
+                    "date": sub.get("date").and_then(|v| v.as_str()),
+                    "color": sub.get("color").and_then(|v| v.as_str()),
+                    "description": sub.get("description").and_then(|v| v.as_str()),
+                }),
+            );
+        }
+    }
+    serde_json::to_string_pretty(&json!({ "milestones": out })).map_err(Into::into)
+}
+
+/// handoff_add_milestone — create a `[milestones.<name>]` entry. Fails if it exists.
+pub fn handle_add(arguments: &Value) -> Result<String> {
+    let path = config_path(arguments)?;
+    let name = require_str(arguments, "name")?;
+    let mut doc = load_doc(&path)?;
+
+    let table = ensure_table(&mut doc, "milestones")?;
+    table.set_implicit(true);
+    if table.contains_key(name) {
+        anyhow::bail!(
+            "Milestone '{name}' already exists. Use handoff_update_milestone to modify it."
+        );
+    }
+    let mut sub = Table::new();
+    apply_fields(&mut sub, arguments);
+    doc["milestones"][name] = Item::Table(sub);
+
+    save_doc(&path, &doc)?;
+    Ok(format!("Added milestone '{name}'"))
+}
+
+/// handoff_update_milestone — patch an existing `[milestones.<name>]` entry.
+pub fn handle_update(arguments: &Value) -> Result<String> {
+    let path = config_path(arguments)?;
+    let name = require_str(arguments, "name")?;
+    let mut doc = load_doc(&path)?;
+
+    let exists = doc
+        .get("milestones")
+        .and_then(|v| v.as_table())
+        .map(|t| t.contains_key(name))
+        .unwrap_or(false);
+    if !exists {
+        anyhow::bail!("Milestone '{name}' not found. Use handoff_add_milestone to create it.");
+    }
+    let sub = ensure_subtable(&mut doc, "milestones", name)?;
+    apply_fields(sub, arguments);
+
+    save_doc(&path, &doc)?;
+    Ok(format!("Updated milestone '{name}'"))
+}
+
+/// handoff_remove_milestone — delete a `[milestones.<name>]` entry.
+pub fn handle_remove(arguments: &Value) -> Result<String> {
+    let path = config_path(arguments)?;
+    let name = require_str(arguments, "name")?;
+    let mut doc = load_doc(&path)?;
+
+    let removed = doc
+        .get_mut("milestones")
+        .and_then(|v| v.as_table_mut())
+        .map(|t| t.remove(name).is_some())
+        .unwrap_or(false);
+    if !removed {
+        anyhow::bail!("Milestone '{name}' not found.");
+    }
+    save_doc(&path, &doc)?;
+    Ok(format!("Removed milestone '{name}'"))
+}
+
+fn apply_fields(table: &mut Table, arguments: &Value) {
+    table.set_implicit(false);
+    set_opt_str(table, "date", arguments.get("date"));
+    set_opt_str(table, "color", arguments.get("color"));
+    set_opt_str(table, "description", arguments.get("description"));
+}

package/src/mcp/handlers/mod.rs

@@ -1,14 +1,26 @@
+pub mod assignees;
+pub mod auto_schedule;
+pub mod bulk_update;
+pub mod calendar;
+pub mod capacity;
 pub mod check_criterion;
 pub mod config;
+pub mod config_crud;
 pub mod dashboard;
+pub mod get_session;
 pub mod get_task;
 pub mod import_context;
 pub mod init;
+pub mod list_sessions;
 pub mod list_tasks;
 pub mod load_context;
+pub mod log_time;
+pub mod metrics;
+pub mod milestones;
 pub mod refer;
 pub mod referrals;
 pub mod save_context;
+pub mod update_session;
 pub mod update_task;
 
 use std::path::PathBuf;
@@ -42,6 +54,25 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "handoff_refer" => refer::handle(arguments),
         "handoff_list_referrals" => referrals::handle_list(arguments),
         "handoff_update_referral" => referrals::handle_update(arguments),
+        "handoff_update_session" => update_session::handle(arguments),
+        "handoff_log_time" => log_time::handle(arguments),
+        "handoff_get_metrics" => metrics::handle(arguments),
+        "handoff_list_sessions" => list_sessions::handle(arguments),
+        "handoff_list_assignees" => assignees::handle(arguments),
+        "handoff_bulk_update_tasks" => bulk_update::handle(arguments),
+        "handoff_get_session" => get_session::handle(arguments),
+        "handoff_get_capacity" => capacity::handle(arguments),
+        "handoff_auto_schedule" => auto_schedule::handle(arguments),
+        "handoff_add_assignee" => assignees::handle_add(arguments),
+        "handoff_update_assignee" => assignees::handle_update(arguments),
+        "handoff_remove_assignee" => assignees::handle_remove(arguments),
+        "handoff_list_milestones" => milestones::handle_list(arguments),
+        "handoff_add_milestone" => milestones::handle_add(arguments),
+        "handoff_update_milestone" => milestones::handle_update(arguments),
+        "handoff_remove_milestone" => milestones::handle_remove(arguments),
+        "handoff_update_calendar" => calendar::handle_update_calendar(arguments),
+        "handoff_update_labels" => calendar::handle_update_labels(arguments),
+        "handoff_start_project" => calendar::handle_start_project(arguments),
         _ => Err(anyhow::anyhow!("Tool not implemented: {name}")),
     };
 

package/src/mcp/handlers/save_context.rs

@@ -9,9 +9,9 @@ use crate::storage::config::read_config;
 use crate::storage::ensure_handoff_exists;
 use crate::storage::git::capture_git_state;
 use crate::storage::sessions::{
-    close_active_sessions, close_session_by_id, enforce_history_limit, generate_session_id,
-    pause_active_sessions, pause_session_by_id, read_active_sessions, write_session_with_status,
-    SessionData,
+    close_session_by_id, enforce_history_limit, generate_session_id, pause_active_sessions,
+    pause_session_by_id, read_active_sessions, update_active_session,
+    update_and_close_active_session, write_session_with_status, SessionData,
 };
 
 pub fn handle(arguments: &Value) -> Result<String> {
@@ -27,11 +27,6 @@ pub fn handle(arguments: &Value) -> Result<String> {
         .get("pause_active")
         .and_then(|v| v.as_bool())
         .unwrap_or(false);
-    let session_status = arguments
-        .get("session_status")
-        .and_then(|v| v.as_str())
-        .unwrap_or("open");
-
     let is_pause_only = arguments
         .get("pause_only")
         .and_then(|v| v.as_bool())
@@ -45,13 +40,6 @@ pub fn handle(arguments: &Value) -> Result<String> {
 
     let summary = summary_opt.unwrap_or("");
 
-    if session_status != "open" && session_status != "active" {
-        anyhow::bail!(
-            "Invalid session_status '{}': must be 'open' or 'active'",
-            session_status
-        );
-    }
-
     let mut total_paused = 0usize;
     if let Some(id) = pause_id {
         if pause_session_by_id(&sessions_dir, id)?.is_some() {
@@ -82,37 +70,18 @@ pub fn handle(arguments: &Value) -> Result<String> {
         return Ok(msg);
     }
 
-    let total_closed = if let Some(id) = close_id {
-        let closed = close_session_by_id(&sessions_dir, id)?;
-        if closed.is_some() {
-            1
-        } else {
-            0
-        }
-    } else if pause_id.is_some() || pause_all {
-        0
-    } else {
-        let active = read_active_sessions(&sessions_dir)?;
-        if active.len() > 1 {
-            let active_ids: Vec<String> = active.iter().filter_map(|s| s.id.clone()).collect();
-            anyhow::bail!(
-                "Multiple active sessions found ({}).\n\
-                 Use close_session_id or pause_session_id to specify which to \
-                 close/pause before saving a new session.",
-                active_ids.join(", ")
-            );
-        }
-        let closed_active = close_active_sessions(&sessions_dir)?;
-        closed_active.len()
-    };
+    let session_status = arguments
+        .get("session_status")
+        .and_then(|v| v.as_str())
+        .unwrap_or("closed");
+    let keep_active = session_status == "active";
 
     let git_state = capture_git_state(&project_dir)?;
     let now = Utc::now().to_rfc3339();
-    let session_id = generate_session_id();
 
-    let data = SessionData {
+    let handoff_updates = SessionData {
         version: 2,
-        id: Some(session_id.clone()),
+        id: None,
         ended_at: Some(now),
         summary: summary.to_string(),
         branch: Some(git_state.branch),
@@ -127,7 +96,45 @@ pub fn handle(arguments: &Value) -> Result<String> {
         environment: arguments.get("environment").cloned(),
     };
 
-    let path = write_session_with_status(&sessions_dir, &data, session_status)?;
+    let (total_closed, path, session_id) = if let Some(id) = close_id {
+        let closed = close_session_by_id(&sessions_dir, id)?;
+        (if closed.is_some() { 1 } else { 0 }, None, None)
+    } else if pause_id.is_some() || pause_all {
+        (0, None, None)
+    } else {
+        let active = read_active_sessions(&sessions_dir)?;
+        if active.len() > 1 {
+            let active_ids: Vec<String> = active.iter().filter_map(|s| s.id.clone()).collect();
+            anyhow::bail!(
+                "Multiple active sessions found ({}).\n\
+                 Use close_session_id or pause_session_id to specify which to \
+                 close/pause before saving context.",
+                active_ids.join(", ")
+            );
+        }
+        if let Some(active_session) = active.first() {
+            let sid = active_session.id.clone().unwrap_or_default();
+            if keep_active {
+                let updated_path = update_active_session(&sessions_dir, &sid, &handoff_updates)?;
+                (0, updated_path, Some(sid))
+            } else {
+                let closed_path =
+                    update_and_close_active_session(&sessions_dir, &sid, &handoff_updates)?;
+                (
+                    if closed_path.is_some() { 1 } else { 0 },
+                    closed_path,
+                    Some(sid),
+                )
+            }
+        } else {
+            let new_id = generate_session_id();
+            let mut data = handoff_updates.clone();
+            data.id = Some(new_id.clone());
+            let target_status = if keep_active { "active" } else { "closed" };
+            let p = write_session_with_status(&sessions_dir, &data, target_status)?;
+            (0, Some(p), Some(new_id))
+        }
+    };
 
     let history_limit = if config_path.exists() {
         read_config(&config_path)
@@ -138,15 +145,21 @@ pub fn handle(arguments: &Value) -> Result<String> {
     };
     let removed = enforce_history_limit(&sessions_dir, history_limit)?;
 
+    let file_display = path
+        .as_ref()
+        .and_then(|p| p.file_name())
+        .map(|n| n.to_string_lossy().to_string())
+        .unwrap_or_else(|| "(none)".to_string());
+    let sid_display = session_id.as_deref().unwrap_or("(no active session)");
     let mut msg = format!(
         "Session saved: {}\nSession ID: {}\nFile: {}",
-        summary,
-        session_id,
-        path.file_name()
-            .map(|n| n.to_string_lossy().to_string())
-            .unwrap_or_default()
+        summary, sid_display, file_display
     );
 
+    if keep_active {
+        msg.push_str("\nSession kept active (session_status: active)");
+    }
+
     if total_paused > 0 {
         msg.push_str(&format!("\nPaused {} session(s)", total_paused));
     }
@@ -173,7 +186,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
         ));
     }
 
-    for w in collect_save_warnings(&data, &project_dir) {
+    for w in collect_save_warnings(&handoff_updates, &project_dir) {
         msg.push_str(&format!("\n{w}"));
     }
 

package/src/mcp/handlers/update_session.rs

@@ -0,0 +1,188 @@
+use anyhow::{Context, Result};
+use serde_json::Value;
+
+use super::resolve_project_dir;
+use crate::storage::ensure_handoff_exists;
+use crate::storage::sessions::{read_active_sessions, SessionData};
+
+pub fn handle(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+    let handoff = ensure_handoff_exists(&project_dir)?;
+    let sessions_dir = handoff.join("sessions");
+
+    let active = read_active_sessions(&sessions_dir)?;
+    if active.is_empty() {
+        anyhow::bail!(
+            "No active session. Call save_context with session_status='active' to create one first."
+        );
+    }
+    if active.len() > 1 {
+        let ids: Vec<String> = active.iter().filter_map(|s| s.id.clone()).collect();
+        anyhow::bail!(
+            "Multiple active sessions ({}). Use save_context to resolve.",
+            ids.join(", ")
+        );
+    }
+
+    let session = &active[0];
+    let sid = session.id.as_deref().unwrap_or("");
+
+    let checklist_index = arguments
+        .get("checklist_index")
+        .and_then(|v| v.as_u64())
+        .map(|v| v as usize);
+    let checklist_checked = arguments.get("checklist_checked").and_then(|v| v.as_bool());
+    let add_checklist_item = arguments.get("add_checklist_item").and_then(|v| v.as_str());
+    let add_decision = arguments.get("add_decision");
+    let add_handoff_note = arguments.get("add_handoff_note");
+    let add_context_pointer = arguments.get("add_context_pointer");
+
+    let mut data = session.clone();
+    let mut changes = Vec::new();
+
+    if let Some(idx) = checklist_index {
+        let checked = checklist_checked.unwrap_or(true);
+        if idx >= data.checklist.len() {
+            anyhow::bail!(
+                "checklist_index {idx} out of range (session has {} items)",
+                data.checklist.len()
+            );
+        }
+        if let Some(item) = data.checklist.get_mut(idx) {
+            item["checked"] = serde_json::json!(checked);
+            let item_text = item
+                .get("item")
+                .and_then(|v| v.as_str())
+                .unwrap_or("(unknown)");
+            changes.push(format!(
+                "checklist[{idx}] '{}' → {}",
+                item_text,
+                if checked { "checked" } else { "unchecked" }
+            ));
+        }
+    }
+
+    if let Some(item_text) = add_checklist_item {
+        let owner = arguments
+            .get("checklist_owner")
+            .and_then(|v| v.as_str())
+            .unwrap_or("ai");
+        data.checklist.push(serde_json::json!({
+            "item": item_text,
+            "checked": false,
+            "owner": owner
+        }));
+        changes.push(format!("added checklist item: '{item_text}'"));
+    }
+
+    if let Some(decision) = add_decision {
+        if decision.is_object() {
+            data.decisions.push(decision.clone());
+            let desc = decision
+                .get("decision")
+                .and_then(|v| v.as_str())
+                .unwrap_or("(decision)");
+            changes.push(format!("added decision: '{desc}'"));
+        } else {
+            anyhow::bail!("add_decision must be an object with at least a 'decision' field");
+        }
+    }
+
+    if let Some(note) = add_handoff_note {
+        if note.is_object() {
+            data.handoff_notes.push(note.clone());
+            let text = note
+                .get("note")
+                .and_then(|v| v.as_str())
+                .unwrap_or("(note)");
+            changes.push(format!("added handoff_note: '{}'", truncate(text, 60)));
+        } else {
+            anyhow::bail!("add_handoff_note must be an object with at least a 'note' field");
+        }
+    }
+
+    if let Some(pointer) = add_context_pointer {
+        if pointer.is_object() {
+            data.context_pointers.push(pointer.clone());
+            let path = pointer
+                .get("path")
+                .and_then(|v| v.as_str())
+                .unwrap_or("(path)");
+            changes.push(format!("added context_pointer: '{path}'"));
+        } else {
+            anyhow::bail!("add_context_pointer must be an object with at least a 'path' field");
+        }
+    }
+
+    if changes.is_empty() {
+        anyhow::bail!(
+            "No updates specified. Use checklist_index, add_checklist_item, \
+             add_decision, add_handoff_note, or add_context_pointer."
+        );
+    }
+
+    write_active_session_data(&sessions_dir, sid, &data)?;
+
+    let mut msg = format!("Session {} updated:", sid);
+    for c in &changes {
+        msg.push_str(&format!("\n  - {c}"));
+    }
+
+    let checked_count = data
+        .checklist
+        .iter()
+        .filter(|item| {
+            item.get("checked")
+                .and_then(|v| v.as_bool())
+                .unwrap_or(false)
+        })
+        .count();
+    msg.push_str(&format!(
+        "\nChecklist: {}/{} checked",
+        checked_count,
+        data.checklist.len()
+    ));
+
+    Ok(msg)
+}
+
+fn truncate(s: &str, max: usize) -> String {
+    if s.len() <= max {
+        s.to_string()
+    } else {
+        format!("{}...", &s[..max])
+    }
+}
+
+fn write_active_session_data(
+    sessions_dir: &std::path::Path,
+    session_id: &str,
+    data: &SessionData,
+) -> Result<()> {
+    let suffix = ".active.json";
+
+    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(suffix) {
+            continue;
+        }
+
+        let content = std::fs::read_to_string(entry.path())
+            .with_context(|| format!("Failed to read session: {}", entry.path().display()))?;
+        let existing: SessionData = serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse session: {}", entry.path().display()))?;
+
+        let file_id = existing.id.as_deref().unwrap_or("");
+        if file_id != session_id {
+            continue;
+        }
+
+        let updated = serde_json::to_string_pretty(data).context("Failed to serialize session")?;
+        crate::storage::atomic_write(entry.path(), updated.as_bytes())
+            .with_context(|| format!("Failed to write session: {}", entry.path().display()))?;
+        return Ok(());
+    }
+
+    anyhow::bail!("Active session '{session_id}' not found on disk")
+}

package/src/mcp/handlers/update_task.rs

@@ -1,3 +1,5 @@
+use std::collections::HashMap;
+
 use anyhow::{Context, Result};
 use chrono::Utc;
 use serde_json::Value;
@@ -103,6 +105,11 @@ fn handle_create(
             .get("order")
             .and_then(|v| v.as_u64())
             .map(|v| v as u32),
+        assignee: task_val
+            .get("assignee")
+            .and_then(|v| v.as_str())
+            .map(String::from),
+        extra: HashMap::new(),
     };
 
     write_task(&task_dir, status, &data)?;
@@ -181,6 +188,11 @@ fn handle_upsert_create(
             .get("order")
             .and_then(|v| v.as_u64())
             .map(|v| v as u32),
+        assignee: task_val
+            .get("assignee")
+            .and_then(|v| v.as_str())
+            .map(String::from),
+        extra: HashMap::new(),
     };
 
     write_task(&task_dir, status, &data)?;
@@ -214,8 +226,32 @@ fn handle_update(tasks_dir: &std::path::Path, task_id: &str, task_val: &Value) -
     if task_val.get("done_criteria").is_some() {
         data.done_criteria = extract_done_criteria(task_val);
     }
-    if task_val.get("schedule").is_some() {
-        data.schedule = extract_schedule(task_val);
+    if let Some(sched_val) = task_val.get("schedule") {
+        // Field-level merge (not full replacement) so that fields not present in
+        // the patch — e.g. actual_hours/remaining_hours accrued by the VSCode timer —
+        // are preserved. Mirrors bulk_update_tasks. (referral ref-20260623-232823)
+        let schedule = data.schedule.get_or_insert_with(Default::default);
+        if let Some(sd) = sched_val.get("start_date").and_then(|v| v.as_str()) {
+            schedule.start_date = Some(sd.to_string());
+        }
+        if let Some(dd) = sched_val.get("due_date").and_then(|v| v.as_str()) {
+            schedule.due_date = Some(dd.to_string());
+        }
+        if let Some(eh) = sched_val.get("estimate_hours").and_then(|v| v.as_f64()) {
+            schedule.estimate_hours = Some(eh);
+        }
+        if let Some(ah) = sched_val.get("actual_hours").and_then(|v| v.as_f64()) {
+            schedule.actual_hours = Some(ah);
+        }
+        if let Some(rh) = sched_val.get("remaining_hours").and_then(|v| v.as_f64()) {
+            schedule.remaining_hours = Some(rh);
+        }
+        if let Some(ms) = sched_val.get("milestone").and_then(|v| v.as_str()) {
+            schedule.milestone = Some(ms.to_string());
+        }
+        if let Some(p) = sched_val.get("pinned").and_then(|v| v.as_bool()) {
+            schedule.pinned = Some(p);
+        }
     }
     if task_val.get("dependencies").is_some() {
         let new_deps = extract_string_array(task_val, "dependencies");
@@ -227,6 +263,12 @@ fn handle_update(tasks_dir: &std::path::Path, task_id: &str, task_val: &Value) -
     if let Some(order) = task_val.get("order").and_then(|v| v.as_u64()) {
         data.order = Some(order as u32);
     }
+    if task_val.get("assignee").is_some() {
+        data.assignee = task_val
+            .get("assignee")
+            .and_then(|v| v.as_str())
+            .map(String::from);
+    }
 
     let new_status = task_val
         .get("status")
@@ -335,9 +377,11 @@ fn extract_schedule(val: &Value) -> Option<Schedule> {
             .map(String::from),
         estimate_hours: sched.get("estimate_hours").and_then(|v| v.as_f64()),
         actual_hours: sched.get("actual_hours").and_then(|v| v.as_f64()),
+        remaining_hours: sched.get("remaining_hours").and_then(|v| v.as_f64()),
         milestone: sched
             .get("milestone")
             .and_then(|v| v.as_str())
             .map(String::from),
+        pinned: sched.get("pinned").and_then(|v| v.as_bool()),
     })
 }

package/src/mcp/router.rs

@@ -48,18 +48,22 @@ fn handle_initialize() -> JsonRpcResponse {
              ## Session Start\n\
              1. Call handoff_load_context (no args needed — uses cwd)\n\
              2. If it returns \"not initialized\", call handoff_init with the project name\n\
-             3. Check the `next_actions` array first — these are the previous session's recommended next steps. Do not re-verify work the previous session already completed\n\n\
+             3. If session_guidance is present, call handoff_save_context with session_status='active' to establish a persistent session before starting work\n\
+             4. Check the `next_actions` array first — these are the previous session's recommended next steps. Do not re-verify work the previous session already completed\n\n\
+             ## During Work — Progressive Updates\n\
+             - Use handoff_update_task to create/update tasks as work progresses\n\
+             - Mark tasks in_progress when starting, done when complete\n\
+             - Use handoff_check_criterion to check off task done_criteria as each item is verified — do not wait until the task is fully done\n\
+             - Use handoff_update_session to progressively update the active session: toggle checklist items, append decisions, notes, or context pointers\n\
+             - When work reaches a point requiring user confirmation, set the task status to review\n\
+             - Record decisions as they are made, not just at session end\n\n\
              ## Session End\n\
              1. Call handoff_save_context with:\n\
                 - summary: one-line description of what was accomplished\n\
                 - decisions: key decisions made (with reason and confidence)\n\
                 - blockers: anything preventing progress\n\
                 - handoff_notes: caution/context/suggestion for the next session\n\
-                - context_pointers: files and line ranges the next session should look at\n\n\
-             ## During Work\n\
-             - Use handoff_update_task to create/update tasks as work progresses\n\
-             - Mark tasks in_progress when starting, done when complete\n\
-             - Record decisions as they are made, not just at session end"
+                - context_pointers: files and line ranges the next session should look at"
                 .to_string(),
         ),
     };