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 <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-09-24 20:26:55 +08:00
1 parent f1e82ce4e5
commit c29d48f38c
4 files changed
+540 -41

No files matched your search

+27
View File
@@ -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;
}
+327
View File
@@ -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<std::process::ChildStdout>,
next_id: i64,
server_name: String,
}
static SESSIONS: Mutex<Vec<(String, Session)>> = 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<Value, String> {
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<Value, String> {
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<Session, String> {
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>), 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<F>(args: &Value, f: F) -> Result<Value, String>
where
F: FnOnce(&mut Session) -> Result<Value, String>,
{
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<Value, String> {
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<Value, String> {
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<Value, String> {
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<Value, String> {
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<Value, String> {
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<Value, String> {
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) {}
+181
View File
@@ -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<Value, String> {
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<Value, String> {
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<Value, String> {
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<Value, String> {
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(),
}))
}
+5 -41
View File
@@ -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<Poli
})
}
fn jev_available() -> 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:<slug>\nor\nEXPLORE\n\nTask:\n",
@@ -385,27 +377,11 @@ fn route_model_request(args: &Value, level: &str) -> Result<Value, String> {
}))
}
fn route_jev(args: &Value) -> Result<Value, String> {
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<Value, String> {
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<Value, String> {
}
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<Value> = Vec::new();
let m = route_marqdo(args)?;
@@ -445,17 +420,6 @@ pub fn route(args: &Value) -> Result<Value, String> {
}
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() {