1use rmcp::model::Tool;
2use rmcp::ErrorData;
3use serde_json::{json, Map, Value};
4
5use crate::server::tool_trait::{
6 get_bool, get_str, get_str_array, McpTool, ToolContext, ToolOutput,
7};
8use crate::tool_defs::tool_def;
9
10pub struct CtxHandoffTool;
11
12impl McpTool for CtxHandoffTool {
13 fn name(&self) -> &'static str {
14 "ctx_handoff"
15 }
16
17 fn tool_def(&self) -> Tool {
18 tool_def(
19 "ctx_handoff",
20 "Context Ledger Protocol (hashed, deterministic, local-first). Actions: create|show|list|pull|clear|export|import.",
21 json!({
22 "type": "object",
23 "properties": {
24 "action": {
25 "type": "string",
26 "enum": ["create", "show", "list", "pull", "clear", "export", "import"],
27 "description": "Operation to perform (default: list)"
28 },
29 "path": { "type": "string", "description": "Ledger file path (for show/pull/import)" },
30 "paths": { "type": "array", "items": { "type": "string" }, "description": "Optional file paths for curated refs (for create/export)" },
31 "format": { "type": "string", "description": "Output format (json|summary)" },
32 "write": { "type": "boolean", "description": "Write export to file" },
33 "privacy": { "type": "string", "description": "Export privacy: redacted (default) | full (admin only)" },
34 "filename": { "type": "string", "description": "Custom filename for export" },
35 "apply_workflow": { "type": "boolean", "description": "For pull/import: apply workflow state (default: true)" },
36 "apply_session": { "type": "boolean", "description": "For pull/import: apply session snapshot (default: true)" },
37 "apply_knowledge": { "type": "boolean", "description": "For pull/import: import knowledge facts (default: true)" }
38 }
39 }),
40 )
41 }
42
43 fn handle(
44 &self,
45 args: &Map<String, Value>,
46 ctx: &ToolContext,
47 ) -> Result<ToolOutput, ErrorData> {
48 let action = get_str(args, "action").unwrap_or_else(|| "list".to_string());
49 let result = match action.as_str() {
50 "list" => handle_list(),
51 "clear" => handle_clear(),
52 "show" => handle_show(args, ctx)?,
53 "create" => handle_create(args, ctx)?,
54 "export" => handle_export(args, ctx)?,
55 "pull" => handle_pull(args, ctx)?,
56 "import" => handle_import(args, ctx)?,
57 _ => "Unknown action. Use: create, show, list, pull, clear, export, import".to_string(),
58 };
59
60 Ok(ToolOutput {
61 text: result,
62 original_tokens: 0,
63 saved_tokens: 0,
64 mode: Some(action),
65 path: None,
66 changed: false,
67 })
68 }
69}
70
71fn handle_list() -> String {
72 let items = crate::core::handoff_ledger::list_ledgers();
73 crate::tools::ctx_handoff::format_list(&items)
74}
75
76fn handle_clear() -> String {
77 let removed = crate::core::handoff_ledger::clear_ledgers().unwrap_or_default();
78 crate::tools::ctx_handoff::format_clear(removed)
79}
80
81fn handle_show(args: &Map<String, Value>, ctx: &ToolContext) -> Result<String, ErrorData> {
82 let path = get_str(args, "path")
83 .ok_or_else(|| ErrorData::invalid_params("path is required for action=show", None))?;
84 let path = ctx
85 .resolve_path_sync(&path)
86 .map_err(|e| ErrorData::invalid_params(e, None))?;
87 let ledger = crate::core::handoff_ledger::load_ledger(std::path::Path::new(&path))
88 .map_err(|e| ErrorData::internal_error(format!("load ledger: {e}"), None))?;
89 Ok(crate::tools::ctx_handoff::format_show(
90 std::path::Path::new(&path),
91 &ledger,
92 ))
93}
94
95fn resolve_curated_refs(
96 args: &Map<String, Value>,
97 ctx: &ToolContext,
98) -> Result<Vec<(String, String)>, ErrorData> {
99 let curated_paths = get_str_array(args, "paths").unwrap_or_default();
100 let mut curated_refs: Vec<(String, String)> = Vec::new();
101 if curated_paths.is_empty() {
102 return Ok(curated_refs);
103 }
104
105 let mut resolved: Vec<String> = Vec::new();
106 for p in curated_paths.into_iter().take(20) {
107 let abs = ctx
108 .resolve_path_sync(&p)
109 .map_err(|e| ErrorData::invalid_params(e, None))?;
110 resolved.push(abs);
111 }
112
113 let cache_handle = ctx.cache.as_ref().unwrap();
114 let mut cache = cache_handle.blocking_write();
115 for abs in &resolved {
116 let mode = if crate::tools::ctx_read::is_instruction_file(abs) {
117 "full"
118 } else {
119 "signatures"
120 };
121 let text =
122 crate::tools::ctx_read::handle_with_task(&mut cache, abs, mode, ctx.crp_mode, None);
123 curated_refs.push((abs.clone(), text));
124 }
125
126 Ok(curated_refs)
127}
128
129fn handle_create(args: &Map<String, Value>, ctx: &ToolContext) -> Result<String, ErrorData> {
130 let curated_refs = resolve_curated_refs(args, ctx)?;
131
132 let session_handle = ctx.session.as_ref().unwrap();
133 let session = { session_handle.blocking_read().clone() };
134 let active_intent = session.active_structured_intent.clone();
135
136 let tool_calls = {
137 let tc = ctx.tool_calls.as_ref().unwrap().blocking_read();
138 tc.clone()
139 };
140 let workflow = { ctx.workflow.as_ref().unwrap().blocking_read().clone() };
141 let agent_id = { ctx.agent_id.as_ref().unwrap().blocking_read().clone() };
142 let client_name = { ctx.client_name.as_ref().unwrap().blocking_read().clone() };
143 let project_root = session.project_root.clone();
144
145 let (ledger, path) = crate::core::handoff_ledger::create_ledger(
146 crate::core::handoff_ledger::CreateLedgerInput {
147 agent_id,
148 client_name: Some(client_name),
149 project_root,
150 session,
151 tool_calls,
152 workflow,
153 curated_refs,
154 },
155 )
156 .map_err(|e| ErrorData::internal_error(format!("create ledger: {e}"), None))?;
157
158 let ctx_ledger = ctx.ledger.as_ref().unwrap().blocking_read();
159 let package = crate::core::handoff_ledger::HandoffPackage::build(
160 ledger.clone(),
161 active_intent.as_ref(),
162 if ctx_ledger.entries.is_empty() {
163 None
164 } else {
165 Some(&*ctx_ledger)
166 },
167 );
168 drop(ctx_ledger);
169
170 let mut output = crate::tools::ctx_handoff::format_created(&path, &ledger);
171 let compact = package.format_compact();
172 if !compact.is_empty() {
173 output.push_str("\n\n");
174 output.push_str(&compact);
175 }
176
177 Ok(output)
178}
179
180fn handle_export(args: &Map<String, Value>, ctx: &ToolContext) -> Result<String, ErrorData> {
181 let curated_refs = resolve_curated_refs(args, ctx)?;
182
183 let session_handle = ctx.session.as_ref().unwrap();
184 let session = { session_handle.blocking_read().clone() };
185
186 let tool_calls = {
187 let tc = ctx.tool_calls.as_ref().unwrap().blocking_read();
188 tc.clone()
189 };
190 let workflow = { ctx.workflow.as_ref().unwrap().blocking_read().clone() };
191 let agent_id = { ctx.agent_id.as_ref().unwrap().blocking_read().clone() };
192 let client_name = { ctx.client_name.as_ref().unwrap().blocking_read().clone() };
193 let project_root = session.project_root.clone();
194
195 let (ledger, _ledger_path) = crate::core::handoff_ledger::create_ledger(
196 crate::core::handoff_ledger::CreateLedgerInput {
197 agent_id,
198 client_name: Some(client_name),
199 project_root: project_root.clone(),
200 session,
201 tool_calls,
202 workflow,
203 curated_refs,
204 },
205 )
206 .map_err(|e| ErrorData::internal_error(format!("create ledger: {e}"), None))?;
207
208 let privacy = crate::core::handoff_transfer_bundle::BundlePrivacyV1::parse(
209 get_str(args, "privacy").as_deref(),
210 );
211 if privacy == crate::core::handoff_transfer_bundle::BundlePrivacyV1::Full
212 && crate::core::roles::active_role_name() != "admin"
213 {
214 return Ok("ERROR: privacy=full requires role 'admin'.".to_string());
215 }
216
217 let bundle = crate::core::handoff_transfer_bundle::build_bundle_v1(
218 ledger,
219 project_root.as_deref(),
220 privacy,
221 );
222 let json = crate::core::handoff_transfer_bundle::serialize_bundle_v1_pretty(&bundle)
223 .map_err(|e| ErrorData::internal_error(e, None))?;
224
225 let write = get_bool(args, "write").unwrap_or(false);
226 let format = get_str(args, "format").unwrap_or_else(|| {
227 if write || get_str(args, "path").is_some() || get_str(args, "filename").is_some() {
228 "summary".to_string()
229 } else {
230 "json".to_string()
231 }
232 });
233
234 let root = project_root.clone().unwrap_or_else(|| {
235 std::env::current_dir()
236 .map_or_else(|_| ".".to_string(), |p| p.to_string_lossy().to_string())
237 });
238 let root_path = std::path::PathBuf::from(&root);
239
240 let mut written: Option<std::path::PathBuf> = None;
241 if write || get_str(args, "path").is_some() || get_str(args, "filename").is_some() {
242 let ts = chrono::Utc::now().format("%Y%m%dT%H%M%SZ").to_string();
243 let candidate = if let Some(p) = get_str(args, "path") {
244 let p = std::path::PathBuf::from(p);
245 if p.is_absolute() {
246 p
247 } else {
248 root_path.join(p)
249 }
250 } else if let Some(name) = get_str(args, "filename") {
251 root_path.join(".lean-ctx").join("proofs").join(name)
252 } else {
253 let session_id = bundle.ledger.session.id.clone();
254 root_path
255 .join(".lean-ctx")
256 .join("proofs")
257 .join(format!("handoff-transfer-bundle-v1_{session_id}_{ts}.json"))
258 };
259
260 let jailed = match crate::core::io_boundary::jail_and_check_path(
261 "ctx_handoff.export",
262 candidate.as_path(),
263 root_path.as_path(),
264 ) {
265 Ok((p, _warning)) => p,
266 Err(e) => return Ok(e),
267 };
268
269 if let Err(e) = crate::core::handoff_transfer_bundle::write_bundle_v1(&jailed, &json) {
270 return Ok(format!("Export write failed: {e}"));
271 }
272
273 let mut ev = crate::core::evidence_ledger::EvidenceLedgerV1::load();
274 let _ = ev.record_artifact_file(
275 "proof:handoff-transfer-bundle-v1",
276 &jailed,
277 chrono::Utc::now(),
278 );
279 let _ = ev.save();
280
281 written = Some(jailed);
282 }
283
284 let out = match format.as_str() {
285 "summary" => crate::tools::ctx_handoff::format_exported(
286 written.as_deref(),
287 bundle.schema_version,
288 json.len(),
289 &bundle.privacy,
290 ),
291 _ => {
292 if let Some(p) = written.as_deref() {
293 format!("{json}\n\npath: {}", p.display())
294 } else {
295 json
296 }
297 }
298 };
299
300 Ok(out)
301}
302
303fn handle_pull(args: &Map<String, Value>, ctx: &ToolContext) -> Result<String, ErrorData> {
304 let path = get_str(args, "path")
305 .ok_or_else(|| ErrorData::invalid_params("path is required for action=pull", None))?;
306 let path = ctx
307 .resolve_path_sync(&path)
308 .map_err(|e| ErrorData::invalid_params(e, None))?;
309 let ledger = crate::core::handoff_ledger::load_ledger(std::path::Path::new(&path))
310 .map_err(|e| ErrorData::internal_error(format!("load ledger: {e}"), None))?;
311
312 let apply_workflow = get_bool(args, "apply_workflow").unwrap_or(true);
313 let apply_session = get_bool(args, "apply_session").unwrap_or(true);
314 let apply_knowledge = get_bool(args, "apply_knowledge").unwrap_or(true);
315
316 if apply_workflow {
317 let mut wf = ctx.workflow.as_ref().unwrap().blocking_write();
318 if ledger
320 .workflow
321 .as_ref()
322 .is_some_and(|r| r.current == "done")
323 {
324 *wf = None;
325 } else {
326 wf.clone_from(&ledger.workflow);
327 }
328 }
329
330 if apply_session {
331 let session_handle = ctx.session.as_ref().unwrap();
332 let mut session = session_handle.blocking_write();
333 if let Some(t) = ledger.session.task.as_deref() {
334 session.set_task(t, None);
335 }
336 for d in &ledger.session.decisions {
337 session.add_decision(d, None);
338 }
339 for f in &ledger.session.findings {
340 session.add_finding(None, None, f);
341 }
342 session.next_steps.clone_from(&ledger.session.next_steps);
343 let _ = session.save();
344 }
345
346 let (knowledge_imported, contradictions) = if apply_knowledge {
347 import_knowledge_from_ledger(ctx, &ledger)?
348 } else {
349 (0, 0)
350 };
351
352 let lines = [
353 "ctx_handoff pull".to_string(),
354 format!(" path: {path}"),
355 format!(" md5: {}", ledger.content_md5),
356 format!(" applied_workflow: {apply_workflow}"),
357 format!(" applied_session: {apply_session}"),
358 format!(" imported_knowledge: {knowledge_imported}"),
359 format!(" contradictions: {contradictions}"),
360 ];
361 Ok(lines.join("\n"))
362}
363
364fn handle_import(args: &Map<String, Value>, ctx: &ToolContext) -> Result<String, ErrorData> {
365 let path = get_str(args, "path")
366 .ok_or_else(|| ErrorData::invalid_params("path is required for action=import", None))?;
367
368 let project_root = ctx.project_root.clone();
369 let root_path = std::path::PathBuf::from(&project_root);
370
371 let candidate = {
372 let p = std::path::PathBuf::from(&path);
373 if p.is_absolute() {
374 p
375 } else {
376 root_path.join(p)
377 }
378 };
379 let jailed = match crate::core::io_boundary::jail_and_check_path(
380 "ctx_handoff.import",
381 candidate.as_path(),
382 root_path.as_path(),
383 ) {
384 Ok((p, _warning)) => p,
385 Err(e) => return Ok(e),
386 };
387
388 let bundle = match crate::core::handoff_transfer_bundle::read_bundle_v1(&jailed) {
389 Ok(b) => b,
390 Err(e) => return Ok(format!("Import failed: {e}")),
391 };
392
393 let warning =
394 crate::core::handoff_transfer_bundle::project_identity_warning(&bundle, &project_root);
395
396 if let Some(ref w) = warning {
397 let source_hash = bundle
398 .project
399 .project_root_hash
400 .as_deref()
401 .unwrap_or("unknown");
402 let target_hash = crate::core::project_hash::hash_project_root(&project_root);
403 let role = crate::core::roles::active_role();
404 if !role.io.allow_cross_project_search {
405 let event = crate::core::memory_boundary::CrossProjectAuditEvent {
406 timestamp: chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
407 event_type: crate::core::memory_boundary::CrossProjectEventType::Import,
408 source_project_hash: source_hash.to_string(),
409 target_project_hash: target_hash,
410 tool: "ctx_handoff".to_string(),
411 action: "import".to_string(),
412 facts_accessed: 0,
413 allowed: false,
414 policy_reason: format!("identity mismatch: {w}"),
415 };
416 crate::core::memory_boundary::record_audit_event(&event);
417 return Ok(format!(
418 "IMPORT BLOCKED: project identity mismatch. {w}\n\
419 Set `io.allow_cross_project_search = true` in your role to allow cross-project imports."
420 ));
421 }
422 }
423
424 let schema_version = bundle.schema_version;
425 let ledger = bundle.ledger;
426
427 let apply_workflow = get_bool(args, "apply_workflow").unwrap_or(true);
428 let apply_session = get_bool(args, "apply_session").unwrap_or(true);
429 let apply_knowledge = get_bool(args, "apply_knowledge").unwrap_or(true);
430
431 if apply_workflow {
432 let mut wf = ctx.workflow.as_ref().unwrap().blocking_write();
433 if ledger
435 .workflow
436 .as_ref()
437 .is_some_and(|r| r.current == "done")
438 {
439 *wf = None;
440 } else {
441 wf.clone_from(&ledger.workflow);
442 }
443 }
444
445 if apply_session {
446 let session_handle = ctx.session.as_ref().unwrap();
447 let mut session = session_handle.blocking_write();
448 if let Some(t) = ledger.session.task.as_deref() {
449 session.set_task(t, None);
450 }
451 for d in &ledger.session.decisions {
452 session.add_decision(d, None);
453 }
454 for f in &ledger.session.findings {
455 session.add_finding(None, None, f);
456 }
457 session.next_steps.clone_from(&ledger.session.next_steps);
458 let _ = session.save();
459 }
460
461 let (knowledge_imported, contradictions) = if apply_knowledge {
462 import_knowledge_from_ledger(ctx, &ledger)?
463 } else {
464 (0, 0)
465 };
466
467 Ok(crate::tools::ctx_handoff::format_imported(
468 jailed.as_path(),
469 schema_version,
470 knowledge_imported,
471 contradictions,
472 warning.as_deref(),
473 ))
474}
475
476fn import_knowledge_from_ledger(
478 ctx: &ToolContext,
479 ledger: &crate::core::handoff_ledger::HandoffLedgerV1,
480) -> Result<(u32, u32), ErrorData> {
481 let project_root = ctx.project_root.clone();
482 let session_id = {
483 let s = ctx.session.as_ref().unwrap().blocking_read();
484 s.id.clone()
485 };
486
487 let policy = match crate::core::config::Config::load().memory_policy_effective() {
488 Ok(p) => p,
489 Err(e) => {
490 let path = crate::core::config::Config::path().map_or_else(
491 || "~/.lean-ctx/config.toml".to_string(),
492 |p| p.display().to_string(),
493 );
494 return Err(ErrorData::internal_error(
495 format!("Error: invalid memory policy: {e}\nFix: edit {path}"),
496 None,
497 ));
498 }
499 };
500
501 let mut knowledge = crate::core::knowledge::ProjectKnowledge::load_or_create(&project_root);
502 let mut imported = 0u32;
503 let mut contradictions = 0u32;
504 for fact in &ledger.knowledge.facts {
505 let c = knowledge.remember(
506 &fact.category,
507 &fact.key,
508 &fact.value,
509 &session_id,
510 fact.confidence,
511 &policy,
512 );
513 if c.is_some() {
514 contradictions += 1;
515 }
516 imported += 1;
517 }
518 let _ = knowledge.run_memory_lifecycle(&policy);
519 let _ = knowledge.save();
520
521 Ok((imported, contradictions))
522}