feat(agent): implement plugin-only durable step workflow with deterministic next/commit/cancel and tests

This commit is contained in:
cflmy committed 2026-11-18 09:51:51 +08:00
1 parent 2dfa0b2a5b
commit 06e61efc51
1 file changed
+346
+346
View File
@@ -0,0 +1,346 @@
//! Plugin-only durable step workflow.
//! No interpreter-frame serialization: every model/tool decision is a checkpointed
//! transition. This state machine issues actions but never executes arbitrary code.
use std::fs::{self, OpenOptions};
use std::path::PathBuf;
use serde_json::{json, Value};
use crate::{choice, parallel, resume};
const MAX_STEPS: usize = 128;
struct Guard(PathBuf);
impl Drop for Guard {
fn drop(&mut self) { let _ = fs::remove_file(&self.0); }
}
fn field<'a>(v: &'a Value, key: &str) -> Result<&'a str, String> {
v.get(key).and_then(Value::as_str).filter(|x| !x.is_empty())
.ok_or_else(|| format!("workflow requires text {key}"))
}
fn safe_key(s: &str) -> bool {
!s.is_empty() && s.len() <= 100
&& s.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
}
fn storage(args: &Value) -> Result<PathBuf, String> {
let rel = args.get("resume_dir").and_then(Value::as_str)
.unwrap_or(".marqdo/agent-resume");
let path = PathBuf::from(rel);
if path.is_absolute() || path.components().any(|part|
matches!(part, std::path::Component::ParentDir | std::path::Component::Prefix(_)))
{
return Err("resume_dir must be relative with no parent traversal".into());
}
let base = crate::host_query_json("cwd").ok()
.and_then(|v| v.as_str().map(PathBuf::from))
.unwrap_or(std::env::current_dir().map_err(|e| e.to_string())?);
let dir = base.join(path);
fs::create_dir_all(&dir).map_err(|e| format!("workflow mkdir: {e}"))?;
Ok(dir)
}
fn lock(args: &Value, id: &str) -> Result<Guard, String> {
if !safe_key(id) {
return Err("workflow id must be <=100 ASCII letters, numbers, - or _".into());
}
let path = storage(args)?.join(format!("{id}.flow-lock"));
OpenOptions::new().write(true).create_new(true).open(&path)
.map_err(|e| format!("workflow busy or stale lock; review before recovering: {e}"))?;
Ok(Guard(path))
}
fn checkpoint_args(args: &Value, id: &str) -> Value {
json!({"id": id, "resume_dir": args.get("resume_dir")})
}
fn read(args: &Value, id: &str) -> Result<Value, String> {
resume::resume_load(&checkpoint_args(args,id))
}
fn context(args: &Value) -> Value {
json!({
"source_revision": args.get("source_revision").cloned().unwrap_or(Value::Null),
"session_id": args.get("session_id").cloned().unwrap_or(Value::Null),
"principal_ref": args.get("principal_ref").cloned().unwrap_or(Value::Null)
})
}
fn check_context(args: &Value, ckpt: &Value) -> bool {
ckpt["meta"]["identity"] == context(args)
}
fn validate_steps(args: &Value) -> Result<Value, String> {
let steps = args.get("steps").and_then(Value::as_array)
.ok_or_else(|| "steps must be a list".to_string())?;
if steps.is_empty() || steps.len() > MAX_STEPS {
return Err("steps must contain 1..=128 items".into());
}
let mut seen = std::collections::HashSet::new();
for s in steps {
let id = field(s, "id")?;
if !safe_key(id) || !seen.insert(id) {
return Err("step ids must be unique safe identifiers".into());
}
let kind = field(s, "kind")?;
if !matches!(kind, "model" | "input" | "skill" | "parallel" | "return") {
return Err(format!("unsupported step kind: {kind}"));
}
if matches!(kind, "model" | "input") {
let options = s.get("options").and_then(Value::as_array)
.ok_or_else(|| "choice step requires options list".to_string())?;
let _ = choice::parse_choice(&json!({"reply":"","options":options}))?;
if kind == "input" { let _ = field(s, "question")?; }
}
if kind == "skill" { let _ = field(s, "skill")?; }
if kind == "parallel" && !s.get("tasks").is_some_and(Value::is_array) {
return Err("parallel step requires tasks array".into());
}
}
Ok(Value::Array(steps.clone()))
}
fn state(ckpt: &Value) -> Result<(&Value,usize),String> {
let meta = ckpt.get("meta").ok_or("missing workflow metadata")?;
if meta.get("kind").and_then(Value::as_str) != Some("MarqdoAgentFlowV1") {
return Err("checkpoint is not a workflow".into());
}
let index = meta.get("cursor").and_then(Value::as_u64)
.ok_or("missing workflow cursor")? as usize;
Ok((meta,index))
}
fn save(args: &Value, id: &str, meta: &Value, status: &str) -> Result<(),String> {
let result = resume::resume_save(&json!({
"id": id,
"resume_dir": args.get("resume_dir"),
"checkpoint_v2": true,
"status": status,
"meta": meta,
"completed_steps": meta["completed"],
"step_id": meta["steps"].get(meta["cursor"].as_u64().unwrap_or(0) as usize)
.and_then(|x| x.get("id")).cloned().unwrap_or(Value::Null)
}))?;
if result["ok"] != true { return Err("workflow checkpoint write failed".into()); }
Ok(())
}
/// Register a bounded, frozen plan. Re-opening never resets a progressed plan.
pub fn open(args: &Value) -> Result<Value,String> {
let id = field(args,"id")?;
let _guard = lock(args,id)?;
let revision = field(args,"source_revision")?;
if revision.len()>256 { return Err("source_revision too long".into()); }
let steps = validate_steps(args)?;
let existing = read(args,id)?;
let identity = context(args);
if existing["found"] == true {
if existing["ok"] == true
&& existing["meta"]["identity"] == identity
&& existing["meta"]["steps"] == steps
{
return next_doc(&existing,id,true);
}
return Ok(json!({"ok":false,"status":"conflict","error":"workflow.id_or_revision_reused"}));
}
let meta = json!({
"kind":"MarqdoAgentFlowV1",
"identity":identity,
"steps":steps,
"cursor":0,
"completed":[],
});
save(args,id,&meta,"running")?;
Ok(json!({"ok":true,"id":id,"status":"created","cursor":0}))
}
fn next_doc(ckpt: &Value, id: &str, reused: bool) -> Result<Value,String> {
let (meta,index)=state(ckpt)?;
let steps = meta["steps"].as_array().ok_or("invalid steps")?;
if index>=steps.len() {
return Ok(json!({"ok":true,"id":id,"status":"succeeded",
"cursor":index,"completed":meta["completed"],"reused":reused}));
}
let step=&steps[index];
let status=ckpt["status"].as_str().unwrap_or("running");
if status=="blocked" || status=="uncertain" || status=="cancelled" {
return Ok(json!({"ok":false,"id":id,"status":status,
"cursor":index,"step":step,"completed":meta["completed"]}));
}
let waiting=match step["kind"].as_str().unwrap_or("") {
"model"=>"waiting_model",
"input"=>"waiting_input",
"skill" | "parallel"=>"ready_tool",
"return"=>"ready_return",
_=>"blocked"
};
Ok(json!({"ok":true,"id":id,"status":waiting,
"cursor":index,"step":step,"completed":meta["completed"],"reused":reused}))
}
/// Query the durable next action. This is non-blocking and does not invoke LLM.
pub fn next(args: &Value) -> Result<Value,String> {
let id=field(args,"id")?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"id":id,"status":"not_found_or_mismatched"}));
}
next_doc(&ckpt,id,false)
}
/// Commit a verified result for the exact current step. All mutations are
/// serialized with a lock; a completed step cannot be committed a second time.
pub fn commit(args: &Value) -> Result<Value,String> {
let id=field(args,"id")?;
let _guard=lock(args,id)?;
let step_id=field(args,"step_id")?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"status":"not_found_or_mismatched"}));
}
let (meta,index)=state(&ckpt)?;
let steps=meta["steps"].as_array().ok_or("invalid steps")?;
let response=args.get("response").ok_or("missing response")?;
if index>=steps.len() {
let previous = meta["completed"].as_array().ok_or("invalid completed")?;
if previous.iter().any(|x|x["step_id"]==step_id && x["value"]==*response) {
return Ok(json!({"ok":true,"status":"succeeded","reused":true}));
}
return Ok(json!({"ok":false,"status":"already_finished"}));
}
let step=&steps[index];
if step["id"]!=step_id {
if meta["completed"].as_array().is_some_and(|list|
list.iter().any(|x|x["step_id"]==step_id && x["value"]==*response))
{
return Ok(json!({"ok":true,"status":"already_committed","reused":true}));
}
return Ok(json!({"ok":false,"status":"step_conflict"}));
}
if ckpt["status"]!="running" {
return Ok(json!({"ok":false,"status":"blocked","reason":ckpt["status"]}));
}
let kind=field(step,"kind")?;
let value = match kind {
"model" | "input" => {
let reply = response.as_str().ok_or("model/input response must be text")?;
let valid=choice::parse_choice(&json!({"options":step["options"],"reply":reply}))?;
if valid["ok"]!=true {
return Ok(json!({"ok":false,"status":"invalid_choice",
"error":valid["error"]}));
}
valid["value"].clone()
}
"skill" => {
if response["ok"]!=true {
return Ok(json!({"ok":false,"status":"tool_not_verified",
"reason":"only verified successful tool result may be committed"}));
}
response.clone()
}
"parallel" => {
let report=parallel::report(&json!({"results":response}))?;
if report["ok"]!=true {
return Ok(json!({"ok":false,
"status": if report["uncertain"].as_u64().unwrap_or(0)>0 {
"uncertain" } else {"partial"},
"report":report,
"reason":"preserve successful children; reconcile or retry failed children separately"}));
}
report
}
"return" => response.clone(),
_ => return Err("invalid step kind".into()),
};
let mut new_meta=meta.clone();
new_meta["cursor"]=json!(index+1);
new_meta["completed"].as_array_mut().ok_or("completed not array")?
.push(json!({"step_id":step_id,"value":value}));
let terminal=index+1==steps.len();
save(args,id,&new_meta,if terminal {"succeeded"} else {"running"})?;
Ok(json!({"ok":true,"id":id,
"status":if terminal {"succeeded"} else {"advanced"},
"cursor":index+1,"value":value,"reused":false}))
}
pub fn cancel(args: &Value) -> Result<Value,String> {
let id=field(args,"id")?;
let _guard=lock(args,id)?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"status":"not_found_or_mismatched"}));
}
if ckpt["status"]=="succeeded" {
return Ok(json!({"ok":false,"status":"already_finished"}));
}
let (meta,_)=state(&ckpt)?;
save(args,id,meta,"cancelled")?;
Ok(json!({"ok":true,"id":id,"status":"cancelled"}))
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::{AtomicU64,Ordering};
static SEQ: AtomicU64=AtomicU64::new(0);
fn fixture()->Value {
let n=SEQ.fetch_add(1,Ordering::Relaxed);
json!({"id":format!("wf-{}-{n}",std::process::id()),
"resume_dir":format!("target/workflow-test-{}-{n}",std::process::id()),
"source_revision":"v1",
"steps":[
{"id":"choose","kind":"model","options":["chat","office"]},
{"id":"answer","kind":"input","question":"OK?","options":["yes","no"]},
{"id":"end","kind":"return"}
]})
}
#[test]
fn nonblocking_model_then_input_then_terminal() {
let a=fixture();
assert_eq!(open(&a).unwrap()["status"],"created");
assert_eq!(next(&a).unwrap()["status"],"waiting_model");
let mut c=a.clone();
c["step_id"]=json!("choose");
c["response"]=json!("office");
assert_eq!(commit(&c).unwrap()["status"],"advanced");
assert_eq!(next(&a).unwrap()["status"],"waiting_input");
assert_eq!(commit(&c).unwrap()["status"],"already_committed");
c["step_id"]=json!("answer");
c["response"]=json!("yes");
assert_eq!(commit(&c).unwrap()["status"],"advanced");
c["step_id"]=json!("end");
c["response"]=json!("ok");
assert_eq!(commit(&c).unwrap()["status"],"succeeded");
assert_eq!(next(&a).unwrap()["status"],"succeeded");
assert_eq!(open(&a).unwrap()["status"],"succeeded");
}
#[test]
fn source_change_conflict_and_invalid_model_choice() {
let a=fixture();
open(&a).unwrap();
let mut bad=a.clone();
bad["source_revision"]=json!("v2");
assert_eq!(next(&bad).unwrap()["status"],"not_found_or_mismatched");
assert_eq!(open(&bad).unwrap()["status"],"conflict");
let mut c=a.clone();
c["step_id"]=json!("choose");
c["response"]=json!("chat or office");
assert_eq!(commit(&c).unwrap()["status"],"invalid_choice");
assert_eq!(next(&a).unwrap()["status"],"waiting_model");
}
#[test]
fn explicit_cancel_stops_future_commits() {
let a=fixture();
open(&a).unwrap();
assert_eq!(cancel(&a).unwrap()["status"],"cancelled");
let mut c=a.clone();
c["step_id"]=json!("choose");
c["response"]=json!("chat");
assert_eq!(commit(&c).unwrap()["status"],"blocked");
}
}