feat(agent): durable user-input gate with idempotent reply, revision and session checks

This commit is contained in:
cflmy committed 2026-11-18 09:37:35 +08:00
1 parent 905a67df32
commit afe31cb2a8
1 file changed
+248
+248
View File
@@ -0,0 +1,248 @@
//! Durable input gates for document-native SKILLs.
//! Pausing is a committed *step boundary*, not serialization of a Rust stack.
//! The caller resumes the next documented step with the saved answer.
use std::fs::{self, OpenOptions};
use std::path::PathBuf;
use serde_json::{json, Value};
use crate::resume;
struct GateLock(PathBuf);
impl Drop for GateLock {
fn drop(&mut self) {
let _ = fs::remove_file(&self.0);
}
}
fn text_arg<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
args.get(key)
.and_then(Value::as_str)
.filter(|s| !s.is_empty())
.ok_or_else(|| format!("missing text `{key}`"))
}
fn valid_id(s: &str) -> bool {
!s.is_empty()
&& s.len() <= 100
&& s.bytes().all(|c| c.is_ascii_alphanumeric() || c == b'-' || c == b'_')
}
fn root(args: &Value) -> Result<PathBuf, String> {
let name = args
.get("resume_dir")
.and_then(Value::as_str)
.unwrap_or(".marqdo/agent-resume");
let path = PathBuf::from(name);
if path.is_absolute()
|| path.components().any(|part| matches!(part, std::path::Component::ParentDir))
{
return Err("resume_dir must be a relative path without '..'".to_string());
}
fs::create_dir_all(&path).map_err(|e| format!("input gate mkdir: {e}"))?;
Ok(path)
}
fn lock(args: &Value, id: &str) -> Result<GateLock, String> {
if !valid_id(id) {
return Err("input gate id must be 1..=100 ASCII letters, numbers, '_' or '-'".into());
}
let path = root(args)?.join(format!("{id}.input-lock"));
OpenOptions::new()
.write(true)
.create_new(true)
.open(&path)
.map_err(|e| format!("input gate is busy or needs reconciliation: {e}"))?;
Ok(GateLock(path))
}
fn options(args: &Value) -> Result<Value, String> {
let choices = args.get("options").and_then(Value::as_array)
.ok_or_else(|| "options must be a list of 1..=32 short labels".to_string())?;
if choices.is_empty() || choices.len() > 32 {
return Err("options must contain 1..=32 choices".into());
}
for v in choices {
let Some(s) = v.as_str() else {
return Err("every option must be text".into());
};
if s.is_empty() || s.len() > 256 {
return Err("each option must contain 1..=256 bytes".into());
}
}
let empty = crate::choice::parse_choice(&json!({
"options": choices, "reply": "__invalid_choice_probe__"
}))?;
// The parser checks duplicates and option size; the probe must not be accepted.
if empty["ok"] == true {
return Err("invalid reserved choice option".into());
}
Ok(Value::Array(choices.to_vec()))
}
/// Create a durable waiting-input checkpoint. Repeated open never resets a
/// previously answered gate. No external effect is performed.
pub fn input_open(args: &Value) -> Result<Value, String> {
let id = text_arg(args, "id")?;
let _lock = lock(args, id)?;
let labels = options(args)?;
let query = text_arg(args, "question")?;
let version = text_arg(args, "source_revision")?;
let read_args = json!({"id": id, "resume_dir": args.get("resume_dir")});
let existing = resume::resume_load(&read_args)?;
if existing["found"] == true {
let meta = &existing["meta"];
let same = meta["question"] == query
&& meta["options"] == labels
&& meta["source_revision"] == version
&& meta["session_id"] == args.get("session_id").unwrap_or(&Value::Null)
&& meta["principal_ref"] == args.get("principal_ref").unwrap_or(&Value::Null);
if same && existing["ok"] == true {
let status = existing["status"].as_str().unwrap_or("unknown");
return Ok(json!({
"ok": true, "id": id, "status": status,
"value": existing["result"], "reused": true,
"question": query, "options": labels
}));
}
return Ok(json!({"ok":false,"id":id,"status":"conflict",
"error":{"code":"input.stale_or_reused_gate"}}));
}
let saved = resume::resume_save(&json!({
"id": id, "resume_dir": args.get("resume_dir"),
"checkpoint_v2": true,
"status": "waiting_input",
"task": query,
"meta": {
"question": query,
"options": labels,
"source_revision": version,
"session_id": args.get("session_id").unwrap_or(&Value::Null),
"principal_ref": args.get("principal_ref").unwrap_or(&Value::Null),
"freeform": args.get("freeform").and_then(Value::as_bool).unwrap_or(true)
}
}))?;
if saved["ok"] != true {
return Err("unable to save input checkpoint".into());
}
Ok(json!({"ok": true, "id":id, "status":"waiting_input", "value":null,
"question":query,"options":labels,"reused":false}))
}
/// Resume a specific gate with a user response. Only a committed answer can be
/// replayed: different duplicate replies conflict instead of re-triggering work.
pub fn input_resume(args: &Value) -> Result<Value, String> {
let id = text_arg(args, "id")?;
let _lock = lock(args, id)?;
let reply = text_arg(args, "reply")?;
if reply.len() > 4096 {
return Err("input reply must not exceed 4096 bytes".into());
}
let version = text_arg(args, "source_revision")?;
let read_args = json!({"id": id, "resume_dir": args.get("resume_dir")});
let existing = resume::resume_load(&read_args)?;
if existing["ok"] != true || existing["schema"] != "CheckpointV2" {
return Ok(json!({"ok":false,"status":"not_found_or_corrupt","id":id}));
}
let meta = &existing["meta"];
if meta["source_revision"] != version
|| meta["session_id"] != *args.get("session_id").unwrap_or(&Value::Null)
|| meta["principal_ref"] != *args.get("principal_ref").unwrap_or(&Value::Null)
{
return Ok(json!({"ok":false,"status":"conflict","id":id,
"error":{"code":"input.scope_or_revision_changed"}}));
}
if existing["status"] == "resumed" {
if existing["result"] == reply {
return Ok(json!({"ok":true,"status":"resumed","id":id,
"value":reply,"reused":true}));
}
return Ok(json!({"ok":false,"status":"conflict","id":id,
"error":{"code":"input.already_answered"}}));
}
if existing["status"] != "waiting_input" {
return Ok(json!({"ok":false,"status":"conflict","id":id}));
}
let allowed = crate::choice::parse_choice(&json!({
"options": meta["options"], "reply": reply
}))?;
let normalized = if allowed["ok"] == true {
allowed["value"].clone()
} else if meta["freeform"] == true && !reply.trim().is_empty() {
json!(reply.trim())
} else {
return Ok(json!({"ok":false,"status":"invalid","id":id,
"error":{"code":"input.invalid_choice"}}));
};
let saved = resume::resume_save(&json!({
"id": id, "resume_dir": args.get("resume_dir"),
"checkpoint_v2": true,
"status": "resumed",
"task": existing["task"],
"meta": meta,
"result": normalized
}))?;
if saved["ok"] != true {
return Err("unable to commit resumed input".into());
}
Ok(json!({"ok":true,"status":"resumed","id":id,
"value":normalized,"reused":false}))
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::{AtomicU64, Ordering};
static SEQ: AtomicU64 = AtomicU64::new(0);
fn fixture() -> (String, String) {
let id = format!("gate_{}_{}",std::process::id(),SEQ.fetch_add(1,Ordering::Relaxed));
let dir = format!("target/mq-gate-test-{id}");
(id, dir)
}
#[test]
fn persists_answer_without_duplicate_side_effect_or_changed_reply() {
let (id, dir) = fixture();
let initial = json!({"id":id,"resume_dir":dir,"question":"Choose?",
"options":["chat","office"],"source_revision":"v1",
"session_id":"s1","principal_ref":"u1","freeform":false});
assert_eq!(input_open(&initial).unwrap()["status"], "waiting_input");
assert_eq!(input_open(&initial).unwrap()["reused"], true);
let v = json!({"id":id,"resume_dir":dir,"reply":"2",
"source_revision":"v1","session_id":"s1","principal_ref":"u1"});
assert_eq!(input_resume(&v).unwrap()["value"], "office");
assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir,
"reply":"office","source_revision":"v1","session_id":"s1",
"principal_ref":"u1"})).unwrap()["reused"], true);
assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir,
"reply":"chat","source_revision":"v1","session_id":"s1",
"principal_ref":"u1"})).unwrap()["status"], "conflict");
assert_eq!(input_open(&initial).unwrap()["status"], "resumed");
}
#[test]
fn prevents_changed_source_or_unauthorized_session() {
let (id, dir) = fixture();
let initial = json!({"id":id,"resume_dir":dir,"question":"Proceed?",
"options":["yes","no"],"source_revision":"v1",
"session_id":"s1","principal_ref":"u1"});
input_open(&initial).unwrap();
for (rev,session) in [("v2","s1"),("v1","other")] {
assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir,"reply":"yes",
"source_revision":rev,"session_id":session,
"principal_ref":"u1"})).unwrap()["status"], "conflict");
}
}
#[test]
fn invalid_choice_keeps_gate_open_and_no_freeform_is_enforced() {
let (id, dir) = fixture();
input_open(&json!({"id":id,"resume_dir":dir,"question":"Pick",
"options":["a","b"],"freeform":false,
"source_revision":"v1"})).unwrap();
assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir,"reply":"??",
"source_revision":"v1"})).unwrap()["status"], "invalid");
assert_eq!(resume::resume_load(&json!({"id":id,"resume_dir":dir})).unwrap()["status"], "waiting_input");
}
}