From c29d48f38cc7d8294eb830088c85d60fda771cf2 Mon Sep 17 00:00:00 2001 From: cflmy Date: Thu, 24 Sep 2026 20:26:55 +0800 Subject: [PATCH] feat(agent): MCP stdio client, resume checkpoints, small-llm router alias Add agent_mcp_client and agent_resume_* plugin APIs. Treat jev as a compat alias of small-llm; auto cascade no longer probes MARQDO_JEV. Co-authored-by: Cursor --- plugins/agent/src/lib.rs | 27 +++ plugins/agent/src/mcp_client.rs | 327 ++++++++++++++++++++++++++++++++ plugins/agent/src/resume.rs | 181 ++++++++++++++++++ plugins/agent/src/route.rs | 46 +---- 4 files changed, 540 insertions(+), 41 deletions(-) create mode 100644 plugins/agent/src/mcp_client.rs create mode 100644 plugins/agent/src/resume.rs diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index c4d2cee..8e1d2b8 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -2,8 +2,10 @@ mod corpus; mod kb; +mod mcp_client; mod mcp_server; mod memory; +mod resume; mod route; use std::collections::HashMap; @@ -924,6 +926,10 @@ kb_ffi!( route::maybe_compile_policy, "agent_maybe_compile_policy" ); +kb_ffi!(agent_resume_save, resume::resume_save, "agent_resume_save"); +kb_ffi!(agent_resume_load, resume::resume_load, "agent_resume_load"); +kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear"); +kb_ffi!(agent_resume_list, resume::resume_list, "agent_resume_list"); #[no_mangle] pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 { @@ -1023,6 +1029,27 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int { return 1; } + if register( + host, + "agent_mcp_client", + "action,command", + mcp_client::agent_mcp_client, + ) != 0 + { + return 1; + } + if register(host, "agent_resume_save", "id,goal,status,round", agent_resume_save) != 0 { + return 1; + } + if register(host, "agent_resume_load", "id,resume_dir", agent_resume_load) != 0 { + return 1; + } + if register(host, "agent_resume_clear", "id,resume_dir", agent_resume_clear) != 0 { + return 1; + } + if register(host, "agent_resume_list", "resume_dir", agent_resume_list) != 0 { + return 1; + } if register(host, "agent_kb_add_alias", "kb_dir,slug,alias", agent_kb_add_alias) != 0 { return 1; } diff --git a/plugins/agent/src/mcp_client.rs b/plugins/agent/src/mcp_client.rs new file mode 100644 index 0000000..3905207 --- /dev/null +++ b/plugins/agent/src/mcp_client.rs @@ -0,0 +1,327 @@ +//! MCP Client (stdio JSON-RPC) — spawn a server process, initialize, list/call tools. + +use serde_json::{json, Value}; +use std::ffi::CStr; +use std::io::{BufRead, BufReader, Write}; +use std::os::raw::{c_char, c_int}; +use std::process::{Child, Command, Stdio}; +use std::sync::Mutex; +use std::time::Duration; + +use crate::{parse_args, set_err, set_out}; + +struct Session { + child: Child, + stdin: std::process::ChildStdin, + reader: BufReader, + next_id: i64, + server_name: String, +} + +static SESSIONS: Mutex> = Mutex::new(Vec::new()); + +fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> { + args.get(key).and_then(|v| v.as_str()).filter(|s| !s.is_empty()) +} + +fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> { + opt_text(args, key).ok_or_else(|| format!("missing text `{key}`")) +} + +fn write_rpc(stdin: &mut impl Write, msg: &Value) -> Result<(), String> { + let s = serde_json::to_string(msg).map_err(|e| e.to_string())?; + writeln!(stdin, "{s}").map_err(|e| format!("mcp client write: {e}"))?; + stdin.flush().map_err(|e| format!("mcp client flush: {e}"))?; + Ok(()) +} + +fn read_rpc(reader: &mut impl BufRead) -> Result { + let mut line = String::new(); + loop { + line.clear(); + let n = reader + .read_line(&mut line) + .map_err(|e| format!("mcp client read: {e}"))?; + if n == 0 { + return Err("mcp client: server closed stdout".into()); + } + let t = line.trim(); + if t.is_empty() { + continue; + } + return serde_json::from_str(t).map_err(|e| format!("mcp client json: {e}")); + } +} + +fn rpc_call(session: &mut Session, method: &str, params: Value) -> Result { + let id = session.next_id; + session.next_id += 1; + let req = json!({ + "jsonrpc": "2.0", + "id": id, + "method": method, + "params": params, + }); + write_rpc(&mut session.stdin, &req)?; + // Read until matching id (skip notifications). + for _ in 0..64 { + let resp = read_rpc(&mut session.reader)?; + if resp.get("id") == Some(&json!(id)) { + if let Some(err) = resp.get("error") { + let msg = err + .get("message") + .and_then(|v| v.as_str()) + .unwrap_or("rpc error"); + return Err(msg.to_string()); + } + return Ok(resp.get("result").cloned().unwrap_or(Value::Null)); + } + } + Err("mcp client: no matching response".into()) +} + +fn spawn_session(command: &str, args: &[String], name: &str) -> Result { + let mut cmd = Command::new(command); + for a in args { + cmd.arg(a); + } + cmd.stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::inherit()); + let mut child = cmd + .spawn() + .map_err(|e| format!("mcp client spawn `{command}`: {e}"))?; + let stdin = child + .stdin + .take() + .ok_or_else(|| "mcp client: no stdin".to_string())?; + let stdout = child + .stdout + .take() + .ok_or_else(|| "mcp client: no stdout".to_string())?; + let mut session = Session { + child, + stdin, + reader: BufReader::new(stdout), + next_id: 1, + server_name: name.to_string(), + }; + // initialize + let _ = rpc_call( + &mut session, + "initialize", + json!({ + "protocolVersion": "2024-11-05", + "capabilities": {}, + "clientInfo": { "name": "marqdo-agent", "version": "0.1.0" } + }), + )?; + // optional initialized notification + let _ = write_rpc( + &mut session.stdin, + &json!({ + "jsonrpc": "2.0", + "method": "notifications/initialized", + "params": {} + }), + ); + let _ = session.server_name; + // Give slow servers a beat (ignore). + let _ = Duration::from_millis(1); + Ok(session) +} + +fn command_args(args: &Value) -> Result<(String, Vec), String> { + let command = arg_text(args, "command")?; + let mut argv = Vec::new(); + if let Some(arr) = args.get("args").and_then(|v| v.as_array()) { + for a in arr { + if let Some(s) = a.as_str() { + argv.push(s.to_string()); + } else { + argv.push(a.to_string()); + } + } + } else if let Some(s) = opt_text(args, "args") { + // space-split simple args + for part in s.split_whitespace() { + argv.push(part.to_string()); + } + } + Ok((command.to_string(), argv)) +} + +fn session_id_of(args: &Value) -> String { + opt_text(args, "session") + .or_else(|| opt_text(args, "id")) + .unwrap_or("default") + .to_string() +} + +fn with_session(args: &Value, f: F) -> Result +where + F: FnOnce(&mut Session) -> Result, +{ + let sid = session_id_of(args); + let mut guard = SESSIONS + .lock() + .map_err(|_| "mcp client: session lock poisoned".to_string())?; + let idx = guard + .iter() + .position(|(id, _)| id == &sid) + .ok_or_else(|| format!("mcp client: no session `{sid}` (call connect first)"))?; + f(&mut guard[idx].1) +} + +fn action_connect(args: &Value) -> Result { + let (command, argv) = command_args(args)?; + let name = opt_text(args, "name").unwrap_or("mcp"); + let sid = session_id_of(args); + let session = spawn_session(&command, &argv, name)?; + let mut guard = SESSIONS + .lock() + .map_err(|_| "mcp client: session lock poisoned".to_string())?; + // Replace existing + guard.retain(|(id, _)| id != &sid); + guard.push((sid.clone(), session)); + Ok(json!({ + "ok": true, + "session": sid, + "transport": "stdio", + "command": command, + })) +} + +fn action_list(args: &Value) -> Result { + with_session(args, |s| { + let result = rpc_call(s, "tools/list", json!({}))?; + let mut out = result; + if let Some(obj) = out.as_object_mut() { + obj.insert("authority".into(), json!("workbook")); + obj.insert("session".into(), json!(session_id_of(args))); + } + Ok(out) + }) +} + +fn action_call(args: &Value) -> Result { + let name = arg_text(args, "name")?; + let arguments = args.get("arguments").cloned().unwrap_or(json!({})); + with_session(args, |s| { + let result = rpc_call( + s, + "tools/call", + json!({ "name": name, "arguments": arguments }), + )?; + let mut out = if result.is_object() { + result + } else { + json!({ "result": result }) + }; + if let Some(obj) = out.as_object_mut() { + obj.insert("authority".into(), json!("workbook")); + obj.insert("session".into(), json!(session_id_of(args))); + } + Ok(out) + }) +} + +fn action_close(args: &Value) -> Result { + let sid = session_id_of(args); + let mut guard = SESSIONS + .lock() + .map_err(|_| "mcp client: session lock poisoned".to_string())?; + if let Some(idx) = guard.iter().position(|(id, _)| id == &sid) { + let (_, mut session) = guard.remove(idx); + let _ = session.child.kill(); + let _ = session.child.wait(); + Ok(json!({ "ok": true, "session": sid, "closed": true })) + } else { + Ok(json!({ "ok": true, "session": sid, "closed": false })) + } +} + +/// One-shot: connect → list or call → close (no persistent session). +fn action_oneshot(args: &Value, kind: &str) -> Result { + let (command, argv) = command_args(args)?; + let name = opt_text(args, "name").unwrap_or("mcp"); + let mut session = spawn_session(&command, &argv, name)?; + let result = match kind { + "list" => { + let r = rpc_call(&mut session, "tools/list", json!({}))?; + Ok(r) + } + "call" => { + let tname = arg_text(args, "tool").or_else(|_| arg_text(args, "name"))?; + // When oneshot call, `name` may be server name — prefer `tool=`. + let tname = opt_text(args, "tool").unwrap_or(tname); + let arguments = args.get("arguments").cloned().unwrap_or(json!({})); + rpc_call( + &mut session, + "tools/call", + json!({ "name": tname, "arguments": arguments }), + ) + } + _ => Err(format!("unknown oneshot kind `{kind}`")), + }; + let _ = session.child.kill(); + let _ = session.child.wait(); + let mut out = result?; + if let Some(obj) = out.as_object_mut() { + obj.insert("authority".into(), json!("workbook")); + obj.insert("transport".into(), json!("stdio")); + } + Ok(out) +} + +pub fn mcp_client(args: &Value) -> Result { + let action = opt_text(args, "action").unwrap_or("list"); + match action { + "connect" => action_connect(args), + "list" => { + if opt_text(args, "command").is_some() && opt_text(args, "session").is_none() { + action_oneshot(args, "list") + } else { + action_list(args) + } + } + "call" => { + if opt_text(args, "command").is_some() && opt_text(args, "session").is_none() { + action_oneshot(args, "call") + } else { + action_call(args) + } + } + "close" | "disconnect" => action_close(args), + other => Err(format!( + "mcp client: unknown action `{other}` (connect|list|call|close)" + )), + } +} + +pub unsafe extern "C" fn agent_mcp_client( + args_json: *const c_char, + out_json: *mut *mut c_char, + err_msg: *mut *mut c_char, +) -> c_int { + let args = match parse_args(args_json) { + Ok(v) => v, + Err(e) => { + set_err(err_msg, &e); + return 1; + } + }; + match mcp_client(&args) { + Ok(v) => { + set_out(out_json, &v.to_string()); + 0 + } + Err(e) => { + set_err(err_msg, &e); + 1 + } + } +} + +#[allow(dead_code)] +fn _unused(_: &CStr) {} diff --git a/plugins/agent/src/resume.rs b/plugins/agent/src/resume.rs new file mode 100644 index 0000000..e2adf80 --- /dev/null +++ b/plugins/agent/src/resume.rs @@ -0,0 +1,181 @@ +//! Agent plan/run resume checkpoints under `.marqdo/agent-resume/`. + +use std::fs; +use std::path::{Path, PathBuf}; + +use serde_json::{json, Value}; + +const DEFAULT_RESUME_DIR: &str = ".marqdo/agent-resume"; + +fn resolve_path(rel: &str) -> PathBuf { + let p = PathBuf::from(rel); + if p.is_absolute() { + return p; + } + if p.exists() { + return p; + } + let base = (|| { + let q = crate::host_query_json("cwd")?; + q.as_str() + .map(PathBuf::from) + .ok_or_else(|| "cwd not text".to_string()) + })() + .or_else(|_| std::env::current_dir().map_err(|e| e.to_string())) + .unwrap_or_else(|_| PathBuf::from(".")); + base.join(p) +} + +fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> { + args.get(key).and_then(|v| v.as_str()).filter(|s| !s.is_empty()) +} + +fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> { + opt_text(args, key).ok_or_else(|| format!("missing text `{key}`")) +} + +fn opt_i64(args: &Value, key: &str, default: i64) -> i64 { + match args.get(key) { + None | Some(Value::Null) => default, + Some(Value::Number(n)) => n.as_i64().unwrap_or(default), + Some(Value::String(s)) => s.parse().unwrap_or(default), + _ => default, + } +} + +fn resume_root(args: &Value) -> PathBuf { + let rel = opt_text(args, "resume_dir").unwrap_or(DEFAULT_RESUME_DIR); + resolve_path(rel) +} + +fn checkpoint_path(root: &Path, id: &str) -> PathBuf { + let safe: String = id + .chars() + .map(|c| { + if c.is_ascii_alphanumeric() || c == '-' || c == '_' { + c + } else { + '_' + } + }) + .collect(); + root.join(format!("{safe}.json")) +} + +fn now_rfc3339() -> String { + chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true) +} + +fn ensure_dir(root: &Path) -> Result<(), String> { + fs::create_dir_all(root).map_err(|e| format!("resume mkdir: {e}")) +} + +pub fn resume_save(args: &Value) -> Result { + let id = arg_text(args, "id")?; + let root = resume_root(args); + ensure_dir(&root)?; + let path = checkpoint_path(&root, id); + let mut doc = json!({ + "id": id, + "updated_at": now_rfc3339(), + }); + if let Some(obj) = doc.as_object_mut() { + for key in [ + "goal", "task", "status", "workbook", "events", "route", "result", "round", "meta", + ] { + if let Some(v) = args.get(key) { + if !v.is_null() { + obj.insert(key.to_string(), v.clone()); + } + } + } + if !obj.contains_key("round") { + obj.insert("round".into(), json!(opt_i64(args, "round", 0))); + } + if !obj.contains_key("status") { + obj.insert("status".into(), json!("running")); + } + } + let text = serde_json::to_string_pretty(&doc).map_err(|e| e.to_string())?; + fs::write(&path, text).map_err(|e| format!("resume save: {e}"))?; + Ok(json!({ + "ok": true, + "id": id, + "path": path.to_string_lossy(), + "updated_at": doc.get("updated_at").cloned().unwrap_or(Value::Null), + })) +} + +pub fn resume_load(args: &Value) -> Result { + let id = arg_text(args, "id")?; + let root = resume_root(args); + let path = checkpoint_path(&root, id); + if !path.is_file() { + return Ok(json!({ + "ok": false, + "found": false, + "id": id, + "path": path.to_string_lossy(), + })); + } + let text = fs::read_to_string(&path).map_err(|e| format!("resume load: {e}"))?; + let mut doc: Value = serde_json::from_str(&text).map_err(|e| format!("resume json: {e}"))?; + if let Some(obj) = doc.as_object_mut() { + obj.insert("ok".into(), json!(true)); + obj.insert("found".into(), json!(true)); + obj.insert("path".into(), json!(path.to_string_lossy())); + } + Ok(doc) +} + +pub fn resume_clear(args: &Value) -> Result { + let id = arg_text(args, "id")?; + let root = resume_root(args); + let path = checkpoint_path(&root, id); + let existed = path.is_file(); + if existed { + fs::remove_file(&path).map_err(|e| format!("resume clear: {e}"))?; + } + Ok(json!({ + "ok": true, + "id": id, + "cleared": existed, + "path": path.to_string_lossy(), + })) +} + +pub fn resume_list(args: &Value) -> Result { + let root = resume_root(args); + if !root.is_dir() { + return Ok(json!({ "ok": true, "items": [], "resume_dir": root.to_string_lossy() })); + } + let mut items = Vec::new(); + let rd = fs::read_dir(&root).map_err(|e| format!("resume list: {e}"))?; + for ent in rd.flatten() { + let p = ent.path(); + if p.extension().and_then(|e| e.to_str()) != Some("json") { + continue; + } + let id = p + .file_stem() + .and_then(|s| s.to_str()) + .unwrap_or("") + .to_string(); + let meta = fs::metadata(&p).ok(); + items.push(json!({ + "id": id, + "path": p.to_string_lossy(), + "len": meta.map(|m| m.len()).unwrap_or(0), + })); + } + items.sort_by(|a, b| { + let ai = a.get("id").and_then(|v| v.as_str()).unwrap_or(""); + let bi = b.get("id").and_then(|v| v.as_str()).unwrap_or(""); + ai.cmp(bi) + }); + Ok(json!({ + "ok": true, + "items": items, + "resume_dir": root.to_string_lossy(), + })) +} diff --git a/plugins/agent/src/route.rs b/plugins/agent/src/route.rs index 5553ea2..1fc168f 100644 --- a/plugins/agent/src/route.rs +++ b/plugins/agent/src/route.rs @@ -1,5 +1,6 @@ //! Adaptive Routing / Policy Compilation (Phase 4). -//! Router is abstract: marqdo | small-llm | jev | llm | auto — Jev is optional. +//! Router is abstract: marqdo | small-llm | llm | auto. +//! `jev` is accepted as an alias of `small-llm` (compat); not a first-class backend. use std::collections::HashMap; use std::fs; @@ -220,15 +221,6 @@ fn match_policy(rules: &[PolicyRule], task: &str, threshold: f64) -> Option bool { - if let Ok(p) = std::env::var("MARQDO_JEV") { - if !p.is_empty() && p != "0" && p != "false" { - return PathBuf::from(&p).is_file() || p == "1" || p == "true"; - } - } - false -} - fn build_route_prompt(task: &str, candidates: &[Value]) -> String { let mut s = String::from( "You are a Marqdo Agent router. Pick the best skill slug for the task, or say EXPLORE.\n\nReply with exactly one line:\nSKILL:\nor\nEXPLORE\n\nTask:\n", @@ -385,27 +377,11 @@ fn route_model_request(args: &Value, level: &str) -> Result { })) } -fn route_jev(args: &Value) -> Result { - if !jev_available() { - return Ok(json!({ - "backend": "jev", - "mode": "unavailable", - "matched": false, - "needs_llm": false, - "confidence": 0.0, - "reason": "jev_not_configured", - })); - } - // Optional external binary path; without a stable Jev ABI we surface a model-shaped request - // so callers can treat Jev like a decision engine when wired later. - route_model_request(args, "jev") -} - /// Cascade Adaptive Router (Phase 4). /// -/// `backend`: `auto` | `marqdo` | `small-llm` | `jev` | `llm` +/// `backend`: `auto` | `marqdo` | `small-llm` | `llm` (`jev` → alias of `small-llm`). /// -/// `auto` order: marqdo policy → kb resolve → (optional jev) → small-llm request → llm request. +/// `auto` order: marqdo policy → kb resolve → small-llm request. pub fn route(args: &Value) -> Result { let backend = opt_text(args, "backend").unwrap_or("auto"); let threshold = opt_f64(args, "threshold", 0.78); @@ -418,9 +394,8 @@ pub fn route(args: &Value) -> Result { } route_resolve_fallback(args) } - "small-llm" | "small_llm" | "small" => route_model_request(args, "small-llm"), + "small-llm" | "small_llm" | "small" | "jev" => route_model_request(args, "small-llm"), "llm" | "large" | "large-llm" => route_model_request(args, "llm"), - "jev" => route_jev(args), "auto" | _ => { let mut trace: Vec = Vec::new(); let m = route_marqdo(args)?; @@ -445,17 +420,6 @@ pub fn route(args: &Value) -> Result { } return Ok(out); } - if jev_available() { - let j = route_jev(args)?; - trace.push(json!({"try": "jev", "mode": j.get("mode")})); - if j.get("needs_llm").and_then(|v| v.as_bool()) == Some(true) { - let mut out = j; - if let Some(obj) = out.as_object_mut() { - obj.insert("trace".into(), Value::Array(trace)); - } - return Ok(out); - } - } // Prefer small-llm request in auto when nothing matched (caller may use large). let mut req = route_model_request(args, "small-llm")?; if let Some(obj) = req.as_object_mut() {