From 6bd90bb2d087f15bc9bd502d91b400330986d128 Mon Sep 17 00:00:00 2001 From: cflmy Date: Tue, 27 Oct 2026 13:28:03 +0800 Subject: [PATCH] feat(agent): ship output channels, ContextPackV2, and effect ledger Open AgentOutputV1/ContextPackV2 capability bits and add EffectLedgerRecordV1 so CheckpointV2 write auto-resume only unlocks on a safe watermark. Co-authored-by: Cursor --- ext/ai/agent.mq.md | 232 ++++++++ plugins/agent/src/context_pack.rs | 266 +++++++++ plugins/agent/src/effects.rs | 555 ++++++++++++++++++ plugins/agent/src/lib.rs | 103 ++++ plugins/agent/src/output.rs | 289 +++++++++ plugins/agent/src/resume.rs | 75 ++- src/workbench/capabilities.rs | 14 +- .../schemas/EffectLedgerRecordV1.schema.json | 46 ++ tests/workbench_contracts.rs | 15 +- 9 files changed, 1577 insertions(+), 18 deletions(-) create mode 100644 plugins/agent/src/context_pack.rs create mode 100644 plugins/agent/src/effects.rs create mode 100644 plugins/agent/src/output.rs create mode 100644 tests/workbench/schemas/EffectLedgerRecordV1.schema.json diff --git a/ext/ai/agent.mq.md b/ext/ai/agent.mq.md index 5680c51..95a372c 100644 --- a/ext/ai/agent.mq.md +++ b/ext/ai/agent.mq.md @@ -285,6 +285,131 @@ Validate schema + authorize; returns ToolCallV1 or ToolResultV1 error (no side e *> agent_tools_prepare_call tool_id=`tool_id` arguments=`arguments` tools=`tools` call_id=`call_id`* +## output_build + + `status`="succeeded" + + `text`="" + + `format`="markdown" + + `answer`=None + + `artifacts`=None + + `citations`=None + + `validation`=None + + `finish_reason`=None + + `recovery_options`=None + + `channels`=None + + `allow_passed_without_report`=False + +Build an `AgentOutputV1` document (M-A4). `validation.status=passed` requires `report_ref`. + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/ai/agent: native agent plugin not found + > sys.exit code=1 + +*> agent_output_build status=`status` text=`text` format=`format` answer=`answer` artifacts=`artifacts` citations=`citations` validation=`validation` finish_reason=`finish_reason` recovery_options=`recovery_options` channels=`channels` allow_passed_without_report=`allow_passed_without_report`* + +## output_apply_policy + + `status`="succeeded" + + `text`="" + + `format`="markdown" + + `answer`=None + + `artifacts`=None + + `citations`=None + + `validation`=None + + `policy`=None + + `schema`=None + + `schema_version`=None + + `finish_reason`=None + + `recovery_options`=None + + `channels`=None + +Apply `ResponsePolicy` (detail / max_chars / max_output_tokens / artifact_allowed) to an AgentOutputV1 or raw text. + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/ai/agent: native agent plugin not found + > sys.exit code=1 + +*> agent_output_apply_policy status=`status` text=`text` format=`format` answer=`answer` artifacts=`artifacts` citations=`citations` validation=`validation` policy=`policy` schema=`schema` schema_version=`schema_version` finish_reason=`finish_reason` recovery_options=`recovery_options` channels=`channels`* + +## output_channel_event + + `channel` + + `delta`="" + + `resource_id`=None + + `meta`=None + +Split a stream delta by channel. Only `answer` sets `append_to_chat=true`. + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/ai/agent: native agent plugin not found + > sys.exit code=1 + +*> agent_output_channel_event channel=`channel` delta=`delta` resource_id=`resource_id` meta=`meta`* + +## output_project_conclusion + + `document`="" + + `text`="" + +Deterministic chat projection from `# 结论` / `# conclusion` (F01 transition). Falls back to the first body paragraph. + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/ai/agent: native agent plugin not found + > sys.exit code=1 + +*> agent_output_project_conclusion document=`document` text=`text`* + +## context_pack_build + + `items`=None + + `budget_tokens`=8000 + + `output_reserve_pct`=20 + + `compact_threshold_pct`=70 + + `goal`=None + + `constraints`=None + +Assemble `ContextPackV2` with origin/trust/priority. Web/tool items cannot be `trust=trusted`. + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/ai/agent: native agent plugin not found + > sys.exit code=1 + +*> agent_context_pack_build items=`items` budget_tokens=`budget_tokens` output_reserve_pct=`output_reserve_pct` compact_threshold_pct=`compact_threshold_pct` goal=`goal` constraints=`constraints`* + +## context_pack_compact + + `items`=None + + `budget_tokens`=8000 + + `output_reserve_pct`=20 + + `compact_threshold_pct`=70 + + `goal`=None + + `constraints`=None + + `schema`=None + + `schema_version`=None + + `available_tokens`=None + + `used_tokens`=None + + `source_event_range`=None + +Compact over-threshold packs; retain goal/constraints/pending_write/plan/trusted anchors (F19). + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/ai/agent: native agent plugin not found + > sys.exit code=1 + +*> agent_context_pack_compact items=`items` budget_tokens=`budget_tokens` output_reserve_pct=`output_reserve_pct` compact_threshold_pct=`compact_threshold_pct` goal=`goal` constraints=`constraints` schema=`schema` schema_version=`schema_version` available_tokens=`available_tokens` used_tokens=`used_tokens` source_event_range=`source_event_range`* + ## render_workbook_skeleton + `goal` + `skeleton`=single @@ -857,6 +982,113 @@ Author entry: load checkpoint for continuation. Returns the checkpoint map (`fou *> resume_load id=`id` resume_dir=`resume_dir`* +## effects_prepare + + `operation_id` + + `idempotency_key` + + `args_digest` + + `effect_class`="write" + + `resource_scope`=None + + `expected_revision`=None + + `result_ref`=None + + `logical_run_id`=None + + `step_id`=None + + `attempt_id`=None + + `ledger_dir`=.marqdo/agent-effects + +Create (or dedupe) an `EffectLedgerRecordV1` in `prepared`. Same idempotency_key + args_digest returns the existing record; same key with different digest is rejected. + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/ai/agent: native agent plugin not found + > sys.exit code=1 + +*> agent_effects_prepare operation_id=`operation_id` idempotency_key=`idempotency_key` args_digest=`args_digest` effect_class=`effect_class` resource_scope=`resource_scope` expected_revision=`expected_revision` result_ref=`result_ref` logical_run_id=`logical_run_id` step_id=`step_id` attempt_id=`attempt_id` ledger_dir=`ledger_dir`* + +## effects_transition + + `operation_id` + + `state` + + `result_ref`=None + + `note`=None + + `reconcile_hint`=None + + `ledger_dir`=.marqdo/agent-effects + +Advance ledger state (`prepared→started→committed|failed_no_effect|unknown→reconciled_*`). + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/ai/agent: native agent plugin not found + > sys.exit code=1 + +*> agent_effects_transition operation_id=`operation_id` state=`state` result_ref=`result_ref` note=`note` reconcile_hint=`reconcile_hint` ledger_dir=`ledger_dir`* + +## effects_get + + `operation_id` + + `ledger_dir`=.marqdo/agent-effects + +Load one ledger record. + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/ai/agent: native agent plugin not found + > sys.exit code=1 + +*> agent_effects_get operation_id=`operation_id` ledger_dir=`ledger_dir`* + +## effects_list + + `ledger_dir`=.marqdo/agent-effects + + `logical_run_id`=None + + `state`=None + +List ledger records (optional filters). + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/ai/agent: native agent plugin not found + > sys.exit code=1 + +*> agent_effects_list ledger_dir=`ledger_dir` logical_run_id=`logical_run_id` state=`state`* + +## effects_watermark + + `ledger_dir`=.marqdo/agent-effects + + `logical_run_id`=None + +Digest committed/open effects for CheckpointV2. `write_auto_resume_safe` is false while unknown or pending writes remain. + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/ai/agent: native agent plugin not found + > sys.exit code=1 + +*> agent_effects_watermark ledger_dir=`ledger_dir` logical_run_id=`logical_run_id`* + +## effects_reconcile + + `operation_id` + + `outcome` + + `result_ref`=None + + `note`=None + + `ledger_dir`=.marqdo/agent-effects + +Reconcile an `unknown` record: `outcome` = committed | no_effect | needs_input. + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/ai/agent: native agent plugin not found + > sys.exit code=1 + +*> agent_effects_reconcile operation_id=`operation_id` outcome=`outcome` result_ref=`result_ref` note=`note` ledger_dir=`ledger_dir`* + --- ## extract_call_args diff --git a/plugins/agent/src/context_pack.rs b/plugins/agent/src/context_pack.rs new file mode 100644 index 0000000..099477d --- /dev/null +++ b/plugins/agent/src/context_pack.rs @@ -0,0 +1,266 @@ +//! ContextPackV2 assemble + compact (M-A4). + +use serde_json::{json, Value}; + +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 item_tokens(item: &Value) -> u64 { + item.get("token_estimate") + .and_then(|v| v.as_u64()) + .unwrap_or_else(|| { + item.get("text") + .and_then(|v| v.as_str()) + .map(|s| (s.chars().count() as u64).div_ceil(2)) + .unwrap_or(32) + }) +} + +fn normalize_item(raw: &Value, default_priority: i64) -> Result { + let origin = raw + .get("origin") + .and_then(|v| v.as_str()) + .unwrap_or("unknown"); + let trust = raw + .get("trust") + .and_then(|v| v.as_str()) + .unwrap_or(match origin { + "system" | "policy" => "trusted", + "user" => "user", + "tool" => "tool", + "web" => "untrusted", + _ => "unknown", + }); + // External / web content must never be trust=trusted. + if matches!(origin, "web" | "tool") && trust == "trusted" { + return Err("tool/web origin cannot have trust=trusted".into()); + } + Ok(json!({ + "origin": origin, + "trust": trust, + "resource_ref": raw.get("resource_ref").cloned().unwrap_or(Value::Null), + "revision": raw.get("revision").cloned().unwrap_or(Value::Null), + "token_estimate": item_tokens(raw), + "priority": raw.get("priority").and_then(|v| v.as_i64()).unwrap_or(default_priority), + "role": raw.get("role").cloned().unwrap_or(json!(origin)), + "text": raw.get("text").cloned().unwrap_or(Value::Null), + "kind": raw.get("kind").cloned().unwrap_or(json!("content")), + "retain": raw.get("retain").and_then(|v| v.as_bool()).unwrap_or(false), + })) +} + +/// Build ContextPackV2 from items + optional budget. +pub fn context_pack_build(args: &Value) -> Result { + let raw_items = args + .get("items") + .and_then(|v| v.as_array()) + .cloned() + .unwrap_or_default(); + let mut items = Vec::new(); + for (i, raw) in raw_items.iter().enumerate() { + items.push(normalize_item(raw, i as i64)?); + } + // Stable priority order: lower priority number first (more important). + items.sort_by(|a, b| { + let pa = a.get("priority").and_then(|v| v.as_i64()).unwrap_or(0); + let pb = b.get("priority").and_then(|v| v.as_i64()).unwrap_or(0); + pa.cmp(&pb) + }); + let budget = args + .get("budget_tokens") + .and_then(|v| v.as_u64()) + .unwrap_or(8_000); + let reserve_pct = args + .get("output_reserve_pct") + .and_then(|v| v.as_u64()) + .unwrap_or(20) + .min(50); + let available = budget.saturating_mul(100 - reserve_pct) / 100; + let used: u64 = items.iter().map(item_tokens).sum(); + Ok(json!({ + "schema": "ContextPackV2", + "schema_version": 2, + "items": items, + "budget_tokens": budget, + "available_tokens": available, + "used_tokens": used, + "output_reserve_pct": reserve_pct, + "compact_threshold_pct": args.get("compact_threshold_pct").and_then(|v| v.as_u64()).unwrap_or(70), + "goal": args.get("goal").cloned().unwrap_or(Value::Null), + "constraints": args.get("constraints").cloned().unwrap_or_else(|| json!([])), + })) +} + +/// Compact pack when over threshold; must retain anchors listed in design §6.2. +pub fn context_pack_compact(args: &Value) -> Result { + let mut pack = if args.get("schema").and_then(|v| v.as_str()) == Some("ContextPackV2") { + args.clone() + } else { + context_pack_build(args)? + }; + let available = pack + .get("available_tokens") + .and_then(|v| v.as_u64()) + .unwrap_or(6400); + let threshold_pct = pack + .get("compact_threshold_pct") + .and_then(|v| v.as_u64()) + .unwrap_or(70); + let threshold = available.saturating_mul(threshold_pct) / 100; + let used = pack + .get("used_tokens") + .and_then(|v| v.as_u64()) + .unwrap_or(0); + if used <= threshold { + if let Some(obj) = pack.as_object_mut() { + obj.insert("compacted".into(), json!(false)); + obj.insert("reason".into(), json!("under_threshold")); + } + return Ok(pack); + } + + let items = pack + .get("items") + .and_then(|v| v.as_array()) + .cloned() + .unwrap_or_default(); + // Retain: goal/constraints (pack fields), retain=true, high priority (<=2), + // pending writes, failures — drop bulky tool dumps first (kind=tool_output, low priority). + let mut kept = Vec::new(); + let mut dropped = Vec::new(); + for item in items { + let retain = item.get("retain").and_then(|v| v.as_bool()).unwrap_or(false); + let priority = item.get("priority").and_then(|v| v.as_i64()).unwrap_or(99); + let kind = item.get("kind").and_then(|v| v.as_str()).unwrap_or(""); + let trust = item.get("trust").and_then(|v| v.as_str()).unwrap_or(""); + let must = retain + || priority <= 2 + || matches!(kind, "goal" | "constraint" | "pending_write" | "plan" | "failure") + || trust == "trusted"; + if must { + kept.push(item); + } else if kind == "tool_output" || priority >= 8 { + dropped.push(item); + } else { + kept.push(item); + } + } + // If still over budget, drop lowest-priority non-retain from kept. + let mut kept_tokens: u64 = kept.iter().map(item_tokens).sum(); + if kept_tokens > threshold { + kept.sort_by(|a, b| { + let pa = a.get("priority").and_then(|v| v.as_i64()).unwrap_or(0); + let pb = b.get("priority").and_then(|v| v.as_i64()).unwrap_or(0); + pb.cmp(&pa) // high priority number first for dropping + }); + let mut next = Vec::new(); + for item in kept.into_iter().rev() { + // rebuild ascending later + let retain = item.get("retain").and_then(|v| v.as_bool()).unwrap_or(false); + let priority = item.get("priority").and_then(|v| v.as_i64()).unwrap_or(99); + let t = item_tokens(&item); + if (retain || priority <= 1) || kept_tokens <= threshold { + next.push(item); + } else if kept_tokens > threshold { + kept_tokens = kept_tokens.saturating_sub(t); + dropped.push(item); + } else { + next.push(item); + } + } + next.sort_by(|a, b| { + let pa = a.get("priority").and_then(|v| v.as_i64()).unwrap_or(0); + let pb = b.get("priority").and_then(|v| v.as_i64()).unwrap_or(0); + pa.cmp(&pb) + }); + kept = next; + kept_tokens = kept.iter().map(item_tokens).sum(); + } + + let digest_src = format!( + "kept={} dropped={} used={}", + kept.len(), + dropped.len(), + kept_tokens + ); + let digest = format!("sha256-lite:{}", simple_hash(&digest_src)); + + if let Some(obj) = pack.as_object_mut() { + obj.insert("items".into(), json!(kept)); + obj.insert("used_tokens".into(), json!(kept_tokens)); + obj.insert("compacted".into(), json!(true)); + obj.insert( + "compaction".into(), + json!({ + "dropped_count": dropped.len(), + "source_event_range": args.get("source_event_range").cloned().unwrap_or(Value::Null), + "digest": digest, + "retained": ["goal", "constraints", "pending_write", "plan", "trusted_policy"], + }), + ); + // Goal / constraints fields stay untouched. + if obj.get("goal").map(|v| v.is_null()).unwrap_or(true) { + if let Some(g) = opt_text(args, "goal") { + obj.insert("goal".into(), json!(g)); + } + } + } + Ok(pack) +} + +fn simple_hash(s: &str) -> u64 { + let mut h: u64 = 0xcbf29ce484222325; + for b in s.as_bytes() { + h ^= u64::from(*b); + h = h.wrapping_mul(0x100000001b3); + } + h +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn build_sorts_and_rejects_trusted_web() { + let pack = context_pack_build(&json!({ + "budget_tokens": 1000, + "items": [ + {"origin": "user", "text": "goal", "priority": 0, "kind": "goal", "retain": true}, + {"origin": "tool", "text": "big dump", "priority": 9, "kind": "tool_output", "token_estimate": 500} + ] + })) + .unwrap(); + assert_eq!(pack["schema"], "ContextPackV2"); + assert_eq!(pack["items"][0]["priority"], 0); + + let bad = context_pack_build(&json!({ + "items": [{"origin": "web", "trust": "trusted", "text": "x"}] + })); + assert!(bad.is_err()); + } + + #[test] + fn compact_keeps_goal_drops_tool_output() { + let pack = context_pack_build(&json!({ + "budget_tokens": 200, + "output_reserve_pct": 20, + "compact_threshold_pct": 50, + "goal": "finish task", + "items": [ + {"origin": "user", "text": "do it", "priority": 0, "kind": "goal", "retain": true, "token_estimate": 20}, + {"origin": "tool", "text": "x".repeat(400), "priority": 9, "kind": "tool_output", "token_estimate": 200} + ] + })) + .unwrap(); + let compacted = context_pack_compact(&pack).unwrap(); + assert_eq!(compacted["compacted"], true); + let items = compacted["items"].as_array().unwrap(); + assert!(items.iter().any(|i| i["kind"] == "goal")); + assert!(!items.iter().any(|i| i["kind"] == "tool_output")); + assert_eq!(compacted["goal"], "finish task"); + } +} diff --git a/plugins/agent/src/effects.rs b/plugins/agent/src/effects.rs new file mode 100644 index 0000000..fcdc348 --- /dev/null +++ b/plugins/agent/src/effects.rs @@ -0,0 +1,555 @@ +//! EffectLedgerRecordV1 — operation receipts for write-safe resume (M-A5 subset). +//! +//! State machine (design §4.2): +//! prepared → started → committed +//! ↘ failed_no_effect +//! ↘ unknown → reconciled_committed | reconciled_no_effect | needs_input + +use std::fs::{self, File, OpenOptions}; +use std::io::Write; +use std::path::{Path, PathBuf}; + +use serde_json::{json, Value}; + +const DEFAULT_LEDGER_DIR: &str = ".marqdo/agent-effects"; + +const STATES: &[&str] = &[ + "prepared", + "started", + "committed", + "failed_no_effect", + "unknown", + "reconciled_committed", + "reconciled_no_effect", + "needs_input", +]; + +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 now_rfc3339() -> String { + chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true) +} + +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 ledger_root(args: &Value) -> Result { + let rel = opt_text(args, "ledger_dir").unwrap_or(DEFAULT_LEDGER_DIR); + let p = PathBuf::from(rel); + if p.is_absolute() { + return Err( + "ledger_dir must be host-relative; absolute client paths are rejected".into(), + ); + } + if rel.contains("..") { + return Err("ledger_dir must not contain '..'".into()); + } + Ok(resolve_path(rel)) +} + +fn safe_id(id: &str) -> String { + id.chars() + .map(|c| { + if c.is_ascii_alphanumeric() || c == '-' || c == '_' { + c + } else { + '_' + } + }) + .collect() +} + +fn record_path(root: &Path, operation_id: &str) -> PathBuf { + root.join(format!("{}.json", safe_id(operation_id))) +} + +fn ensure_dir(root: &Path) -> Result<(), String> { + fs::create_dir_all(root).map_err(|e| format!("effects mkdir: {e}")) +} + +fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> { + let parent = path + .parent() + .ok_or_else(|| "ledger path has no parent".to_string())?; + ensure_dir(parent)?; + let tmp_name = format!( + ".{}.tmp-{}-{}", + path.file_name() + .and_then(|s| s.to_str()) + .unwrap_or("op.json"), + std::process::id(), + now_rfc3339().replace(':', "") + ); + let tmp = parent.join(tmp_name); + let text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?; + { + let mut f = OpenOptions::new() + .create(true) + .write(true) + .truncate(true) + .open(&tmp) + .map_err(|e| format!("effects temp open: {e}"))?; + f.write_all(text.as_bytes()) + .map_err(|e| format!("effects temp write: {e}"))?; + f.flush().map_err(|e| format!("effects temp flush: {e}"))?; + f.sync_all() + .map_err(|e| format!("effects temp fsync: {e}"))?; + } + if let Ok(dir) = File::open(parent) { + let _ = dir.sync_all(); + } + fs::rename(&tmp, path).map_err(|e| { + let _ = fs::remove_file(&tmp); + format!("effects atomic rename: {e}") + })?; + Ok(()) +} + +fn load_record(path: &Path) -> Result, String> { + if !path.is_file() { + return Ok(None); + } + let text = fs::read_to_string(path).map_err(|e| format!("effects read: {e}"))?; + let doc: Value = serde_json::from_str(&text).map_err(|e| format!("effects corrupt: {e}"))?; + Ok(Some(doc)) +} + +fn valid_transition(from: &str, to: &str) -> bool { + matches!( + (from, to), + ("prepared", "started") + | ("started", "committed") + | ("started", "failed_no_effect") + | ("started", "unknown") + | ("unknown", "reconciled_committed") + | ("unknown", "reconciled_no_effect") + | ("unknown", "needs_input") + // Idempotent no-ops / crash retries of the same terminal. + | ("committed", "committed") + | ("failed_no_effect", "failed_no_effect") + | ("reconciled_committed", "reconciled_committed") + | ("reconciled_no_effect", "reconciled_no_effect") + | ("needs_input", "needs_input") + // Re-prepare of same op is handled separately via idempotency. + | ("prepared", "prepared") + ) +} + +fn effect_class_ok(c: &str) -> bool { + matches!(c, "read" | "write" | "execute" | "external_write" | "none") +} + +/// Prepare (or return existing) an EffectLedgerRecordV1. +pub fn effects_prepare(args: &Value) -> Result { + let operation_id = arg_text(args, "operation_id")?; + let idempotency_key = arg_text(args, "idempotency_key")?; + let args_digest = arg_text(args, "args_digest")?; + let effect_class = opt_text(args, "effect_class").unwrap_or("write"); + if !effect_class_ok(effect_class) { + return Err(format!("invalid effect_class={effect_class}")); + } + let root = ledger_root(args)?; + ensure_dir(&root)?; + let path = record_path(&root, operation_id); + + if let Some(existing) = load_record(&path)? { + let same_key = existing + .get("idempotency_key") + .and_then(|v| v.as_str()) + == Some(idempotency_key); + let same_digest = existing.get("args_digest").and_then(|v| v.as_str()) == Some(args_digest); + if same_key && same_digest { + return Ok(json!({ + "ok": true, + "deduped": true, + "record": existing, + })); + } + if same_key && !same_digest { + return Err( + "idempotency_key collision: same key with different args_digest".into(), + ); + } + // Different operation_id path can't collide; same path different key is corrupt reuse. + return Err("operation_id already exists with different idempotency_key".into()); + } + + // Also scan for same idempotency_key under other operation_ids in this ledger dir. + if let Ok(rd) = fs::read_dir(&root) { + for ent in rd.flatten() { + let p = ent.path(); + if p.extension().and_then(|e| e.to_str()) != Some("json") { + continue; + } + if let Ok(Some(doc)) = load_record(&p) { + if doc.get("idempotency_key").and_then(|v| v.as_str()) == Some(idempotency_key) { + let dig = doc.get("args_digest").and_then(|v| v.as_str()); + if dig == Some(args_digest) { + return Ok(json!({ + "ok": true, + "deduped": true, + "record": doc, + })); + } + return Err( + "idempotency_key collision: same key with different args_digest".into(), + ); + } + } + } + } + + let doc = json!({ + "schema": "EffectLedgerRecordV1", + "schema_version": 1, + "operation_id": operation_id, + "idempotency_key": idempotency_key, + "args_digest": args_digest, + "resource_scope": args.get("resource_scope").cloned().unwrap_or(Value::Null), + "expected_revision": args.get("expected_revision").cloned().unwrap_or(Value::Null), + "effect_class": effect_class, + "result_ref": args.get("result_ref").cloned().unwrap_or(Value::Null), + "state": "prepared", + "logical_run_id": args.get("logical_run_id").cloned().unwrap_or(Value::Null), + "step_id": args.get("step_id").cloned().unwrap_or(Value::Null), + "attempt_id": args.get("attempt_id").cloned().unwrap_or(Value::Null), + "prepared_at": now_rfc3339(), + "updated_at": now_rfc3339(), + }); + atomic_write_json(&path, &doc)?; + Ok(json!({ + "ok": true, + "deduped": false, + "record": doc, + "path": path.to_string_lossy(), + })) +} + +/// Transition an existing record to a new state. +pub fn effects_transition(args: &Value) -> Result { + let operation_id = arg_text(args, "operation_id")?; + let to = arg_text(args, "state")?; + if !STATES.contains(&to) { + return Err(format!("invalid state={to}")); + } + let root = ledger_root(args)?; + let path = record_path(&root, operation_id); + let mut doc = load_record(&path)? + .ok_or_else(|| format!("operation_id not found: {operation_id}"))?; + let from = doc + .get("state") + .and_then(|v| v.as_str()) + .unwrap_or("prepared") + .to_string(); + if !valid_transition(&from, to) { + return Err(format!("illegal transition {from} → {to}")); + } + if let Some(obj) = doc.as_object_mut() { + obj.insert("state".into(), json!(to)); + obj.insert("updated_at".into(), json!(now_rfc3339())); + if let Some(r) = args.get("result_ref") { + if !r.is_null() { + obj.insert("result_ref".into(), r.clone()); + } + } + if let Some(n) = args.get("note") { + if !n.is_null() { + obj.insert("note".into(), n.clone()); + } + } + if to == "unknown" || to.starts_with("reconciled") { + obj.insert( + "reconcile_hint".into(), + args.get("reconcile_hint") + .cloned() + .unwrap_or_else(|| json!("check receipt / resource revision")), + ); + } + } + atomic_write_json(&path, &doc)?; + Ok(json!({ + "ok": true, + "from": from, + "to": to, + "record": doc, + })) +} + +pub fn effects_get(args: &Value) -> Result { + let operation_id = arg_text(args, "operation_id")?; + let root = ledger_root(args)?; + let path = record_path(&root, operation_id); + match load_record(&path)? { + Some(doc) => Ok(json!({ + "ok": true, + "found": true, + "record": doc, + "path": path.to_string_lossy(), + })), + None => Ok(json!({ + "ok": true, + "found": false, + "operation_id": operation_id, + "path": path.to_string_lossy(), + })), + } +} + +pub fn effects_list(args: &Value) -> Result { + let root = ledger_root(args)?; + let mut records = Vec::new(); + if root.is_dir() { + let mut paths: Vec<_> = fs::read_dir(&root) + .map_err(|e| e.to_string())? + .flatten() + .map(|e| e.path()) + .filter(|p| p.extension().and_then(|e| e.to_str()) == Some("json")) + .collect(); + paths.sort(); + for p in paths { + if let Ok(Some(doc)) = load_record(&p) { + if let Some(run) = opt_text(args, "logical_run_id") { + if doc.get("logical_run_id").and_then(|v| v.as_str()) != Some(run) { + continue; + } + } + if let Some(st) = opt_text(args, "state") { + if doc.get("state").and_then(|v| v.as_str()) != Some(st) { + continue; + } + } + records.push(doc); + } + } + } + Ok(json!({ + "ok": true, + "count": records.len(), + "records": records, + "ledger_dir": root.to_string_lossy(), + })) +} + +/// Compute a watermark digest over committed / reconciled records for a run. +pub fn effects_watermark(args: &Value) -> Result { + let listed = effects_list(args)?; + let records = listed + .get("records") + .and_then(|v| v.as_array()) + .cloned() + .unwrap_or_default(); + let mut parts = Vec::new(); + let mut open_unknown = 0u64; + let mut pending_writes = 0u64; + for r in &records { + let state = r.get("state").and_then(|v| v.as_str()).unwrap_or(""); + let oid = r.get("operation_id").and_then(|v| v.as_str()).unwrap_or(""); + let cls = r.get("effect_class").and_then(|v| v.as_str()).unwrap_or(""); + parts.push(format!("{oid}:{state}")); + if state == "unknown" || state == "needs_input" { + open_unknown += 1; + } + if matches!(cls, "write" | "external_write" | "execute") + && matches!(state, "prepared" | "started" | "unknown" | "needs_input") + { + pending_writes += 1; + } + } + parts.sort(); + let joined = parts.join("|"); + let digest = format!("sha256-lite:{:x}", fnv64(&joined)); + let write_auto_resume_safe = open_unknown == 0 && pending_writes == 0; + Ok(json!({ + "ok": true, + "schema": "EffectLedgerWatermarkV1", + "schema_version": 1, + "watermark": digest, + "record_count": records.len(), + "open_unknown": open_unknown, + "pending_writes": pending_writes, + "write_auto_resume_safe": write_auto_resume_safe, + "logical_run_id": args.get("logical_run_id").cloned().unwrap_or(Value::Null), + })) +} + +/// Reconcile an `unknown` record after inspecting the external receipt / revision. +pub fn effects_reconcile(args: &Value) -> Result { + let outcome = arg_text(args, "outcome")?; // committed | no_effect | needs_input + let state = match outcome { + "committed" => "reconciled_committed", + "no_effect" => "reconciled_no_effect", + "needs_input" => "needs_input", + other => return Err(format!("invalid reconcile outcome={other}")), + }; + let mut targs = args.clone(); + if let Some(obj) = targs.as_object_mut() { + obj.insert("state".into(), json!(state)); + } + effects_transition(&targs) +} + +fn fnv64(s: &str) -> u64 { + let mut h: u64 = 0xcbf29ce484222325; + for b in s.as_bytes() { + h ^= u64::from(*b); + h = h.wrapping_mul(0x100000001b3); + } + h +} + +#[cfg(test)] +mod tests { + use super::*; + + fn scratch(tag: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!( + "mq-effects-{}-{}-{}", + tag, + std::process::id(), + now_rfc3339().replace(':', "") + )); + let _ = fs::remove_dir_all(&dir); + fs::create_dir_all(&dir).unwrap(); + dir + } + + #[test] + fn prepare_dedupe_and_collision() { + let dir = scratch("prep"); + let prev = std::env::current_dir().unwrap(); + std::env::set_current_dir(&dir).unwrap(); + let a = effects_prepare(&json!({ + "operation_id": "op1", + "idempotency_key": "idem1", + "args_digest": "sha256:a", + "effect_class": "write", + "ledger_dir": "led", + "logical_run_id": "run1", + })) + .unwrap(); + assert_eq!(a["deduped"], false); + assert_eq!(a["record"]["state"], "prepared"); + + let again = effects_prepare(&json!({ + "operation_id": "op1", + "idempotency_key": "idem1", + "args_digest": "sha256:a", + "ledger_dir": "led", + })) + .unwrap(); + assert_eq!(again["deduped"], true); + + let clash = effects_prepare(&json!({ + "operation_id": "op2", + "idempotency_key": "idem1", + "args_digest": "sha256:b", + "ledger_dir": "led", + })); + assert!(clash.unwrap_err().contains("collision")); + + std::env::set_current_dir(prev).unwrap(); + let _ = fs::remove_dir_all(&dir); + } + + #[test] + fn transition_and_watermark_gates_write_resume() { + let dir = scratch("wm"); + let prev = std::env::current_dir().unwrap(); + std::env::set_current_dir(&dir).unwrap(); + effects_prepare(&json!({ + "operation_id": "op_w", + "idempotency_key": "idem_w", + "args_digest": "sha256:w", + "effect_class": "write", + "ledger_dir": "led", + "logical_run_id": "run1", + })) + .unwrap(); + effects_transition(&json!({ + "operation_id": "op_w", + "state": "started", + "ledger_dir": "led", + })) + .unwrap(); + // Crash window: unknown — write auto-resume must stay closed. + effects_transition(&json!({ + "operation_id": "op_w", + "state": "unknown", + "ledger_dir": "led", + })) + .unwrap(); + let wm1 = effects_watermark(&json!({ + "ledger_dir": "led", + "logical_run_id": "run1", + })) + .unwrap(); + assert_eq!(wm1["write_auto_resume_safe"], false); + assert_eq!(wm1["open_unknown"], 1); + + effects_reconcile(&json!({ + "operation_id": "op_w", + "outcome": "committed", + "ledger_dir": "led", + "result_ref": "receipt:1", + })) + .unwrap(); + let wm2 = effects_watermark(&json!({ + "ledger_dir": "led", + "logical_run_id": "run1", + })) + .unwrap(); + assert_eq!(wm2["write_auto_resume_safe"], true); + assert_eq!(wm2["open_unknown"], 0); + assert!(wm2["watermark"].as_str().unwrap().starts_with("sha256-lite:")); + + std::env::set_current_dir(prev).unwrap(); + let _ = fs::remove_dir_all(&dir); + } + + #[test] + fn illegal_skip_started() { + let dir = scratch("bad"); + let prev = std::env::current_dir().unwrap(); + std::env::set_current_dir(&dir).unwrap(); + effects_prepare(&json!({ + "operation_id": "op_x", + "idempotency_key": "idem_x", + "args_digest": "sha256:x", + "ledger_dir": "led", + })) + .unwrap(); + let err = effects_transition(&json!({ + "operation_id": "op_x", + "state": "committed", + "ledger_dir": "led", + })) + .unwrap_err(); + assert!(err.contains("illegal transition")); + std::env::set_current_dir(prev).unwrap(); + let _ = fs::remove_dir_all(&dir); + } +} diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 48d2fce..daf70f4 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -1,12 +1,15 @@ //! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query + agent-kb + v2 memory + adaptive route. +mod context_pack; mod corpus; +mod effects; mod eng; mod error; mod kb; mod mcp_client; mod mcp_server; mod memory; +mod output; mod resume; mod route; mod sandbox; @@ -849,6 +852,58 @@ kb_ffi!( tools::seed_from_allowlist_args, "agent_tools_seed_allowlist" ); +kb_ffi!(agent_output_build, output::output_build, "agent_output_build"); +kb_ffi!( + agent_output_apply_policy, + output::output_apply_policy, + "agent_output_apply_policy" +); +kb_ffi!( + agent_output_channel_event, + output::output_channel_event, + "agent_output_channel_event" +); +kb_ffi!( + agent_output_project_conclusion, + output::output_project_conclusion, + "agent_output_project_conclusion" +); +kb_ffi!( + agent_context_pack_build, + context_pack::context_pack_build, + "agent_context_pack_build" +); +kb_ffi!( + agent_context_pack_compact, + context_pack::context_pack_compact, + "agent_context_pack_compact" +); +kb_ffi!( + agent_effects_prepare, + effects::effects_prepare, + "agent_effects_prepare" +); +kb_ffi!( + agent_effects_transition, + effects::effects_transition, + "agent_effects_transition" +); +kb_ffi!(agent_effects_get, effects::effects_get, "agent_effects_get"); +kb_ffi!( + agent_effects_list, + effects::effects_list, + "agent_effects_list" +); +kb_ffi!( + agent_effects_watermark, + effects::effects_watermark, + "agent_effects_watermark" +); +kb_ffi!( + agent_effects_reconcile, + effects::effects_reconcile, + "agent_effects_reconcile" +); kb_ffi!(agent_eng_preflight, eng::eng_preflight, "agent_eng_preflight"); kb_ffi!(agent_eng_reuse, eng::eng_reuse, "agent_eng_reuse"); kb_ffi!(agent_eng_bind_execute, eng::eng_bind_execute, "agent_eng_bind_execute"); @@ -912,6 +967,54 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int agent_tools_register_eng_defaults, ), ("agent_tools_seed_allowlist", "tools", agent_tools_seed_allowlist), + ("agent_output_build", "status,text,validation", agent_output_build), + ( + "agent_output_apply_policy", + "status,text,policy", + agent_output_apply_policy, + ), + ( + "agent_output_channel_event", + "channel,delta", + agent_output_channel_event, + ), + ( + "agent_output_project_conclusion", + "document", + agent_output_project_conclusion, + ), + ( + "agent_context_pack_build", + "items,budget_tokens", + agent_context_pack_build, + ), + ( + "agent_context_pack_compact", + "items,budget_tokens", + agent_context_pack_compact, + ), + ( + "agent_effects_prepare", + "operation_id,idempotency_key,args_digest", + agent_effects_prepare, + ), + ( + "agent_effects_transition", + "operation_id,state", + agent_effects_transition, + ), + ("agent_effects_get", "operation_id", agent_effects_get), + ("agent_effects_list", "ledger_dir", agent_effects_list), + ( + "agent_effects_watermark", + "ledger_dir", + agent_effects_watermark, + ), + ( + "agent_effects_reconcile", + "operation_id,outcome", + agent_effects_reconcile, + ), ("agent_kb_add_alias", "kb_dir,slug,alias", agent_kb_add_alias), ("agent_kb_promote", "kb_dir,goal,workbook", agent_kb_promote), ("agent_kb_quarantine", "kb_dir,slug", agent_kb_quarantine), diff --git a/plugins/agent/src/output.rs b/plugins/agent/src/output.rs new file mode 100644 index 0000000..a105c18 --- /dev/null +++ b/plugins/agent/src/output.rs @@ -0,0 +1,289 @@ +//! AgentOutputV1 + ResponsePolicy (M-A4). + +use serde_json::{json, Value}; + +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()) +} + +/// Normalize / build an AgentOutputV1 document. +pub fn output_build(args: &Value) -> Result { + let status = opt_text(args, "status").unwrap_or("succeeded"); + if !matches!( + status, + "succeeded" | "partial" | "failed" | "needs_input" | "cancelled" + ) { + return Err(format!("invalid status={status}")); + } + let answer = args.get("answer").cloned().unwrap_or_else(|| { + json!({ + "format": opt_text(args, "format").unwrap_or("markdown"), + "text": opt_text(args, "text").unwrap_or(""), + }) + }); + let validation = args.get("validation").cloned().unwrap_or_else(|| { + json!({ + "status": "not_run", + "report_ref": Value::Null + }) + }); + let vstatus = validation + .get("status") + .and_then(|v| v.as_str()) + .unwrap_or("not_run"); + if !matches!( + vstatus, + "passed" | "failed" | "not_applicable" | "not_run" + ) { + return Err(format!("invalid validation.status={vstatus}")); + } + // Never claim passed without an explicit report when status says passed. + if vstatus == "passed" && validation.get("report_ref").map(|v| v.is_null()).unwrap_or(true) { + if args.get("allow_passed_without_report").and_then(|v| v.as_bool()) != Some(true) { + return Err("validation.status=passed requires report_ref".into()); + } + } + + let finish = opt_text(args, "finish_reason").unwrap_or(match status { + "succeeded" => "completed", + "partial" => "length_limited", + "cancelled" => "cancelled", + "needs_input" => "needs_input", + _ => "error", + }); + + Ok(json!({ + "schema": "AgentOutputV1", + "schema_version": 1, + "status": status, + "answer": answer, + "artifacts": args.get("artifacts").cloned().unwrap_or_else(|| json!([])), + "citations": args.get("citations").cloned().unwrap_or_else(|| json!([])), + "validation": validation, + "finish_reason": finish, + "recovery_options": args.get("recovery_options").cloned().unwrap_or_else(|| json!([])), + "channels": args.get("channels").cloned().unwrap_or_else(|| json!({ + "answer": true, + "artifact": true, + "progress": true, + "diagnostic": true + })), + })) +} + +/// Apply ResponsePolicy budgets to an answer text → possibly partial output. +pub fn output_apply_policy(args: &Value) -> Result { + let mut out = if args.get("schema").and_then(|v| v.as_str()) == Some("AgentOutputV1") { + args.clone() + } else { + output_build(args)? + }; + let policy = args.get("policy").cloned().unwrap_or(json!({})); + let detail = policy + .get("detail") + .and_then(|v| v.as_str()) + .unwrap_or("standard"); + let max_chars = match policy.get("max_chars").and_then(|v| v.as_u64()) { + Some(n) if n > 0 => n as usize, + _ => match detail { + "concise" => 250, + "detailed" => 8_000, + _ => 700, + }, + }; + let max_tokens = policy + .get("max_output_tokens") + .and_then(|v| v.as_u64()) + .unwrap_or(0) as usize; + let artifact_allowed = policy + .get("artifact_allowed") + .and_then(|v| v.as_bool()) + .unwrap_or(true); + + let text = out + .pointer("/answer/text") + .and_then(|v| v.as_str()) + .unwrap_or("") + .to_string(); + // Soft char budget (CJK-aware enough: count Unicode scalars). + let chars: Vec = text.chars().collect(); + let mut finish = out + .get("finish_reason") + .and_then(|v| v.as_str()) + .unwrap_or("completed") + .to_string(); + let mut status = out + .get("status") + .and_then(|v| v.as_str()) + .unwrap_or("succeeded") + .to_string(); + let mut answer_text = text.clone(); + if chars.len() > max_chars { + answer_text = chars.into_iter().take(max_chars).collect(); + // Prefer not to cut mid-code fence if possible — soft trim at last newline. + if let Some(pos) = answer_text.rfind('\n') { + if pos > max_chars / 2 { + answer_text.truncate(pos); + } + } + finish = "length_limited".into(); + if status == "succeeded" { + status = "partial".into(); + } + } + // Token budget is advisory here (chars/4 approx) when max_output_tokens set. + if max_tokens > 0 { + let approx = answer_text.chars().count().div_ceil(2); // rough CJK token estimate + if approx > max_tokens { + let keep = max_tokens.saturating_mul(2); + answer_text = answer_text.chars().take(keep).collect(); + finish = "length_limited".into(); + status = "partial".into(); + } + } + + if let Some(obj) = out.as_object_mut() { + obj.insert("status".into(), json!(status)); + obj.insert("finish_reason".into(), json!(finish)); + if let Some(ans) = obj.get_mut("answer").and_then(|v| v.as_object_mut()) { + ans.insert("text".into(), json!(answer_text)); + } + if !artifact_allowed { + obj.insert("artifacts".into(), json!([])); + } + obj.insert( + "response_policy".into(), + json!({ + "detail": detail, + "max_chars": max_chars, + "max_output_tokens": max_tokens, + "artifact_allowed": artifact_allowed, + }), + ); + } + Ok(out) +} + +/// Split a channel event. Only `answer` is meant for chat body append. +pub fn output_channel_event(args: &Value) -> Result { + let channel = opt_text(args, "channel").ok_or_else(|| "missing channel".to_string())?; + if !matches!(channel, "answer" | "artifact" | "progress" | "diagnostic") { + return Err(format!("invalid channel={channel}")); + } + let delta = opt_text(args, "delta").unwrap_or(""); + Ok(json!({ + "schema": "AgentChannelEventV1", + "schema_version": 1, + "channel": channel, + "delta": delta, + "append_to_chat": channel == "answer", + "resource_id": args.get("resource_id").cloned().unwrap_or(Value::Null), + "meta": args.get("meta").cloned().unwrap_or(json!({})), + })) +} + +/// Project `# 结论` (or first non-empty paragraph) from a marqdo document for chat. +pub fn output_project_conclusion(args: &Value) -> Result { + let doc = opt_text(args, "document") + .or_else(|| opt_text(args, "text")) + .unwrap_or(""); + let mut in_conclusion = false; + let mut buf = String::new(); + for line in doc.lines() { + let t = line.trim(); + if t == "# 结论" || t.eq_ignore_ascii_case("# conclusion") { + in_conclusion = true; + continue; + } + if in_conclusion { + if t.starts_with("# ") { + break; + } + if t.is_empty() { + if !buf.is_empty() { + buf.push('\n'); + } + continue; + } + if !buf.is_empty() { + buf.push('\n'); + } + buf.push_str(t); + } + } + if buf.trim().is_empty() { + // Fallback: first non-frontmatter paragraph. + let mut past_fm = !doc.starts_with("---"); + let mut fm_done = past_fm; + for line in doc.lines() { + if !fm_done { + if line.trim() == "---" { + if past_fm { + fm_done = true; + } else { + past_fm = true; + } + } + continue; + } + let t = line.trim(); + if t.is_empty() || t.starts_with('#') || t.starts_with('|') { + continue; + } + buf = t.to_string(); + break; + } + } + Ok(json!({ + "ok": true, + "text": buf.trim(), + "channel": "answer", + "source": "conclusion_projection", + })) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn build_and_policy_limits() { + let out = output_build(&json!({ + "status": "succeeded", + "text": "短答", + "validation": {"status": "not_applicable", "report_ref": null} + })) + .unwrap(); + assert_eq!(out["schema"], "AgentOutputV1"); + assert_eq!(out["answer"]["text"], "短答"); + + let long: String = "字".repeat(400); + let limited = output_apply_policy(&json!({ + "status": "succeeded", + "text": long, + "validation": {"status": "not_applicable"}, + "policy": {"detail": "concise", "max_chars": 100} + })) + .unwrap(); + assert_eq!(limited["status"], "partial"); + assert_eq!(limited["finish_reason"], "length_limited"); + assert!(limited["answer"]["text"].as_str().unwrap().chars().count() <= 100); + } + + #[test] + fn channel_answer_only_appends_chat() { + let e = output_channel_event(&json!({"channel": "progress", "delta": "检索中"})).unwrap(); + assert_eq!(e["append_to_chat"], false); + let a = output_channel_event(&json!({"channel": "answer", "delta": "hi"})).unwrap(); + assert_eq!(a["append_to_chat"], true); + } + + #[test] + fn project_conclusion() { + let doc = "---\ntitle: t\n---\n\n# 任务\n问\n\n# 结论\n答案是 42。\n\n# main\nprint\n"; + let p = output_project_conclusion(&json!({"document": doc})).unwrap(); + assert!(p["text"].as_str().unwrap().contains("42")); + } +} diff --git a/plugins/agent/src/resume.rs b/plugins/agent/src/resume.rs index 3184d20..25835fa 100644 --- a/plugins/agent/src/resume.rs +++ b/plugins/agent/src/resume.rs @@ -231,17 +231,40 @@ pub fn resume_save(args: &Value) -> Result { })) } +fn watermark_allows_write_auto(wm: &Value) -> bool { + match wm { + Value::Null => false, + Value::String(s) => !s.is_empty(), + Value::Object(obj) => { + // Prefer explicit safety bit from effects_watermark; bare digest objects + // without the bit are treated as unsafe (open unknown / pending writes). + match obj.get("write_auto_resume_safe").and_then(|v| v.as_bool()) { + Some(b) => b, + None => obj + .get("watermark") + .and_then(|v| v.as_str()) + .map(|s| !s.is_empty()) + .unwrap_or(false) + && obj.get("open_unknown").and_then(|v| v.as_u64()).unwrap_or(1) == 0 + && obj.get("pending_writes").and_then(|v| v.as_u64()).unwrap_or(1) == 0, + } + } + _ => false, + } +} + fn annotate_recovery(mut doc: Value) -> Value { let is_v2 = doc.get("schema").and_then(|v| v.as_str()) == Some("CheckpointV2") && doc.get("schema_version").and_then(|v| v.as_u64()) == Some(2); - let has_ledger = doc + let wm = doc .get("effect_ledger_watermark") - .map(|v| !v.is_null()) - .unwrap_or(false); - let (recovery_mode, write_auto_resume) = if is_v2 && has_ledger { + .cloned() + .unwrap_or(Value::Null); + let ledger_safe = watermark_allows_write_auto(&wm); + let (recovery_mode, write_auto_resume) = if is_v2 && ledger_safe { ("checkpoint_v2", true) } else if is_v2 { - // V2 without ledger: read resume OK; write auto-resume still closed. + // V2 without a safe ledger watermark: read resume OK; write auto-resume closed. ("checkpoint_v2_read_only", false) } else { // Legacy: no effect info → manual_review; never auto redo writes. @@ -426,6 +449,48 @@ mod tests { assert_eq!(legacy["write_auto_resume"], false); assert_eq!(legacy["legacy_adaptation"], "manual_review"); + // V2 + safe watermark → write_auto_resume opens. + let _ = resume_save(&json!({ + "id": "run_safe", + "schema": "CheckpointV2", + "schema_version": 2, + "status": "running", + "round": 3, + "resume_dir": rel, + "attempt_id": "a2", + "effect_ledger_watermark": { + "schema": "EffectLedgerWatermarkV1", + "watermark": "sha256-lite:abc", + "write_auto_resume_safe": true, + "open_unknown": 0, + "pending_writes": 0 + } + })) + .unwrap(); + let safe = resume_load(&json!({"id": "run_safe", "resume_dir": rel})).unwrap(); + assert_eq!(safe["recovery_mode"], "checkpoint_v2"); + assert_eq!(safe["write_auto_resume"], true); + + // Unsafe watermark (open unknown) keeps write auto-resume closed. + let _ = resume_save(&json!({ + "id": "run_unsafe", + "schema": "CheckpointV2", + "schema_version": 2, + "status": "running", + "round": 4, + "resume_dir": rel, + "attempt_id": "a3", + "effect_ledger_watermark": { + "watermark": "sha256-lite:def", + "write_auto_resume_safe": false, + "open_unknown": 1 + } + })) + .unwrap(); + let unsafe_ck = resume_load(&json!({"id": "run_unsafe", "resume_dir": rel})).unwrap(); + assert_eq!(unsafe_ck["recovery_mode"], "checkpoint_v2_read_only"); + assert_eq!(unsafe_ck["write_auto_resume"], false); + std::env::set_current_dir(prev).unwrap(); let _ = fs::remove_dir_all(&dir); } diff --git a/src/workbench/capabilities.rs b/src/workbench/capabilities.rs index 5736cb4..caaca22 100644 --- a/src/workbench/capabilities.rs +++ b/src/workbench/capabilities.rs @@ -117,16 +117,12 @@ pub fn probe_capabilities(params: &Value) -> Value { features.insert("view.document".into(), json!(0)); features.insert("view.reference_resolve".into(), json!(0)); } - // M-A0–M-A3: protocol capability bits (tool_schema after M-A2 registry). + // M-A0–M-A4: protocol capability bits. features.insert("agent.error_v1".into(), json!(1)); features.insert("agent.checkpoint_v2".into(), json!(1)); features.insert("agent.tool_schema_v1".into(), json!(1)); - for (k, v) in [ - ("agent.output_channels_v1", 0), - ("agent.context_pack_v2", 0), - ] { - features.insert(k.into(), json!(v)); - } + features.insert("agent.output_channels_v1".into(), json!(1)); + features.insert("agent.context_pack_v2".into(), json!(1)); #[cfg(feature = "view")] { features.insert("resource.view_v1".into(), json!(1)); @@ -250,8 +246,8 @@ mod tests { assert_eq!(caps["features"]["agent.error_v1"], 1); assert_eq!(caps["features"]["agent.checkpoint_v2"], 1); assert_eq!(caps["features"]["agent.tool_schema_v1"], 1); - assert_eq!(caps["features"]["agent.output_channels_v1"], 0); - assert_eq!(caps["features"]["agent.context_pack_v2"], 0); + assert_eq!(caps["features"]["agent.output_channels_v1"], 1); + assert_eq!(caps["features"]["agent.context_pack_v2"], 1); #[cfg(feature = "view")] assert_eq!(caps["features"]["resource.view_v1"], 1); #[cfg(not(feature = "view"))] diff --git a/tests/workbench/schemas/EffectLedgerRecordV1.schema.json b/tests/workbench/schemas/EffectLedgerRecordV1.schema.json new file mode 100644 index 0000000..c840c36 --- /dev/null +++ b/tests/workbench/schemas/EffectLedgerRecordV1.schema.json @@ -0,0 +1,46 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "marqdo://contracts/EffectLedgerRecordV1", + "title": "EffectLedgerRecordV1", + "type": "object", + "required": [ + "schema", + "schema_version", + "operation_id", + "idempotency_key", + "args_digest", + "effect_class", + "state" + ], + "properties": { + "schema": { "const": "EffectLedgerRecordV1" }, + "schema_version": { "const": 1 }, + "operation_id": { "type": "string" }, + "idempotency_key": { "type": "string" }, + "args_digest": { "type": "string" }, + "resource_scope": { "type": ["string", "null"] }, + "expected_revision": { "type": ["string", "null"] }, + "effect_class": { + "type": "string", + "enum": ["read", "write", "execute", "external_write", "none"] + }, + "result_ref": { "type": ["string", "null"] }, + "state": { + "type": "string", + "enum": [ + "prepared", + "started", + "committed", + "failed_no_effect", + "unknown", + "reconciled_committed", + "reconciled_no_effect", + "needs_input" + ] + }, + "logical_run_id": { "type": ["string", "null"] }, + "step_id": { "type": ["string", "null"] }, + "attempt_id": { "type": ["string", "null"] } + }, + "additionalProperties": true +} diff --git a/tests/workbench_contracts.rs b/tests/workbench_contracts.rs index 573031e..1b15776 100644 --- a/tests/workbench_contracts.rs +++ b/tests/workbench_contracts.rs @@ -136,6 +136,12 @@ fn ma0_agent_reliability_protocol_freeze() { assert_eq!(legacy["id"], "legacy_resume_01"); let ledger = fixture("effect_ledger_v1.json"); + assert_required( + &ledger, + &schema("EffectLedgerRecordV1.schema.json"), + "effect_ledger", + ); + assert_eq!(ledger["schema"], "EffectLedgerRecordV1"); assert_eq!(ledger["state"], "prepared"); assert_eq!(ledger["effect_class"], "write"); @@ -182,13 +188,12 @@ fn ma0_agent_reliability_protocol_freeze() { let caps = mlsp("capabilities", serde_json::json!({})); assert_eq!(caps["ok"], true, "{caps}"); let features = &caps["result"]["features"]; - for bit in ["agent.output_channels_v1", "agent.context_pack_v2"] { - assert_eq!(features[bit], 0, "{bit} must stay 0 until emitters land"); - } - // M-A1–M-A3: error + checkpoint + tool schema + resource view emitters are live. + // M-A1–M-A4: agent reliability emitters are live. assert_eq!(features["agent.error_v1"], 1); assert_eq!(features["agent.checkpoint_v2"], 1); assert_eq!(features["agent.tool_schema_v1"], 1); + assert_eq!(features["agent.output_channels_v1"], 1); + assert_eq!(features["agent.context_pack_v2"], 1); assert_eq!(features["resource.view_v1"], 1); let formats = caps["result"]["extract_formats"] @@ -220,6 +225,8 @@ fn ma0_agent_reliability_protocol_freeze() { assert_eq!(down["result"]["features"]["agent.error_v1"], 1); assert_eq!(down["result"]["features"]["agent.checkpoint_v2"], 1); assert_eq!(down["result"]["features"]["agent.tool_schema_v1"], 1); + assert_eq!(down["result"]["features"]["agent.output_channels_v1"], 1); + assert_eq!(down["result"]["features"]["agent.context_pack_v2"], 1); assert_eq!(down["result"]["features"]["resource.view_v1"], 1); }