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 <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-10-27 13:28:03 +08:00
1 parent 4683f2e067
commit 6bd90bb2d0
9 files changed
+1577 -18

No files matched your search

+232
View File
@@ -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
+266
View File
@@ -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<Value, String> {
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<Value, String> {
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<Value, String> {
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");
}
}
+555
View File
@@ -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<PathBuf, String> {
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<Option<Value>, 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<Value, String> {
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<Value, String> {
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<Value, String> {
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<Value, String> {
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<Value, String> {
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<Value, String> {
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);
}
}
+103
View File
@@ -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),
+289
View File
@@ -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<Value, String> {
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<Value, String> {
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<char> = 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<Value, String> {
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<Value, String> {
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"));
}
}
+70 -5
View File
@@ -231,17 +231,40 @@ pub fn resume_save(args: &Value) -> Result<Value, String> {
}))
}
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);
}
+5 -9
View File
@@ -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"))]
@@ -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
}
+11 -4
View File
@@ -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);
}