From 1a39a53d93c0f0e707c43181afa19f370544aa2c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:30:03 +0800 Subject: [PATCH 01/66] feat(agent): add fail-closed small-model choice parser and tests --- plugins/agent/src/choice.rs | 152 ++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 plugins/agent/src/choice.rs diff --git a/plugins/agent/src/choice.rs b/plugins/agent/src/choice.rs new file mode 100644 index 0000000..5a4e300 --- /dev/null +++ b/plugins/agent/src/choice.rs @@ -0,0 +1,152 @@ +//! Fail-closed choice parsing for small-model routing. +//! This module only extracts a value; it never resolves or executes a SKILL. + +use serde_json::{json, Value}; + +fn canonical(s: &str) -> String { + s.trim() + .trim_matches(|c: char| matches!(c, '"' | '\'' | '`' | '“' | '”' | '‘' | '’')) + .trim() + .to_lowercase() +} + +fn strip_fence(s: &str) -> &str { + let s = s.trim(); + if !s.starts_with("```") { + return s; + } + let Some(start) = s.find('\n') else { + return s; + }; + let body = &s[start + 1..]; + let Some(end) = body.find("```") else { + return s; + }; + if !body[end + 3..].trim().is_empty() { + return s; + } + body[..end].trim() +} + +fn strip_label(s: &str) -> &str { + let s = s.trim(); + let Some((head, tail)) = s.split_once([':', ':']) else { + return s; + }; + if matches!( + head.trim().to_lowercase().as_str(), + "choice" | "option" | "selected" | "选择" | "选项" | "答案" + ) { + tail.trim() + } else { + s + } +} + +fn single_choice(options: &[String], reply: &str) -> Option { + let raw = strip_label(strip_fence(reply)); + let value = canonical(raw); + // Never infer a routing decision from arbitrary prose. + let matches: Vec<&String> = options + .iter() + .filter(|opt| canonical(opt) == value) + .collect(); + if matches.len() == 1 { + return Some(matches[0].clone()); + } + // A bare number denotes a 1-based index into the allowed list. + if let Ok(index) = value.parse::() { + if index > 0 && index <= options.len() { + return Some(options[index - 1].clone()); + } + } + None +} + +/// Parse one permitted option from a small model response. +/// Returns a status rather than treating arbitrary prose as a tool target. +pub fn parse_choice(args: &Value) -> Result { + let reply = args + .get("reply") + .and_then(Value::as_str) + .ok_or_else(|| "missing text `reply`".to_string())?; + let options = args + .get("options") + .and_then(Value::as_array) + .ok_or_else(|| "options must be an array of strings".to_string())?; + if options.is_empty() || options.len() > 64 { + return Err("options must contain 1..=64 entries".to_string()); + } + let mut allowed = Vec::with_capacity(options.len()); + for option in options { + let name = option + .as_str() + .ok_or_else(|| "each option must be a string".to_string())?; + if name.trim().is_empty() || name.len() > 128 { + return Err("each option must contain 1..=128 UTF-8 bytes".to_string()); + } + if allowed.iter().any(|p: &String| canonical(p) == canonical(name)) { + return Err("options must be unique after normalization".to_string()); + } + allowed.push(name.to_string()); + } + if let Some(value) = single_choice(&allowed, reply) { + Ok(json!({"ok": true, "value": value, "status": "accepted"})) + } else { + Ok(json!({ + "ok": false, + "value": null, + "status": "invalid", + "error": { + "code": "model.invalid_choice", + "category": "invalid_output", + "retryable": false, + "recovery_action": "repair_output" + } + })) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn check(reply: &str) -> Value { + parse_choice(&json!({"options": ["chat", "office"], "reply": reply})).unwrap() + } + + #[test] + fn accepts_exact_label_fence_and_number() { + assert_eq!(check("chat")["value"], "chat"); + assert_eq!(check(" CHAT ")["value"], "chat"); + assert_eq!(check("选择:office")["value"], "office"); + assert_eq!(check("```text\nchat\n```")["value"], "chat"); + assert_eq!(check("2")["value"], "office"); + } + + #[test] + fn refuses_prose_conflicts_and_out_of_range() { + for reply in ["请选择 chat", "chat 或 office", "choice: chat,因为更合适", "3", ""] { + let result = check(reply); + assert_eq!(result["ok"], false, "accepted {reply:?}"); + assert_eq!(result["value"], Value::Null); + } + } + + #[test] + fn rejects_invalid_options_before_parsing() { + for options in [ + json!([]), + json!(["chat", "CHAT"]), + json!(["chat", 10]), + json!([""]), + ] { + assert!(parse_choice(&json!({"options": options, "reply": "chat"})).is_err()); + } + } + + #[test] + fn never_extracts_arbitrary_skill_path() { + assert_eq!(check("../../private.mq.md")["ok"], false); + } +} From b3867c46dbaee154ed710e26f390a8c14226e297 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:30:10 +0800 Subject: [PATCH 02/66] feat(agent): register native choice parser in plugin ABI --- plugins/agent/src/lib.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 1bcabef..23783c6 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -1,5 +1,6 @@ //! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query + agent-kb + v2 memory + adaptive route. +mod choice; mod context_pack; mod corpus; mod effects; @@ -834,6 +835,7 @@ kb_ffi!(agent_resume_save, resume::resume_save, "agent_resume_save"); kb_ffi!(agent_resume_load, resume::resume_load, "agent_resume_load"); kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear"); kb_ffi!(agent_resume_list, resume::resume_list, "agent_resume_list"); +kb_ffi!(agent_choice_parse, choice::parse_choice, "agent_choice_parse"); kb_ffi!(agent_error_make, error::make_error, "agent_error_make"); kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry"); kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register"); @@ -963,6 +965,7 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_resume_load", "id,resume_dir", agent_resume_load), ("agent_resume_clear", "id,resume_dir", agent_resume_clear), ("agent_resume_list", "resume_dir", agent_resume_list), + ("agent_choice_parse", "reply,options", agent_choice_parse), ("agent_error_make", "code,message,category", agent_error_make), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_tools_register", "spec,specs", agent_tools_register), From c299efe58971134b8af63508e31e7ca0a50d8c99 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:30:22 +0800 Subject: [PATCH 03/66] feat(ai): add thin model-choice and parallel-document flow library --- ext/ai/flow.mq.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 ext/ai/flow.mq.md diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md new file mode 100644 index 0000000..123f4a4 --- /dev/null +++ b/ext/ai/flow.mq.md @@ -0,0 +1,83 @@ +--- +markup: occlusion +title: AI flow — small-model choices and bounded subtasks +description: Short model decisions, verified options and concurrent Marqdo documents. +import: + llm: ext/ai/llm.mq.md + json: lib/json.mq.md + plugin: lib/plugin.mq.md + subtask: lib/subtask.mq.md +--- + +This is the thin author-facing layer. A model returns a candidate; Marqdo checks +it before routing. Invalid choices are not SKILL paths and never execute. +Only the requested function and its inputs need to be in the model prompt. + +## parse_choice + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| reply | text | required | Raw model reply, treated as data | +| options | list | required | Allowed names, not paths or commands | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | {ok,value,status} or {ok:false,error} | + +Parsing accepts one exact name, a labeled name, a fenced name or a 1-based +index. Ambiguous prose fails closed. Parsing never runs a tool or SKILL. + +We retain **p = [Locate the installed agent plugin](plugin.native_path(name="agent"))**. +1. p + We **[Load the agent plugin](plugin.load(path=`p`))**. +2. * + Return *[Missing native parser](json.parse(text="{\"ok\":false,\"status\":\"unavailable\",\"value\":null}"))*. + +Return *[Parse and verify the choice](agent_choice_parse(reply=`reply`, options=`options`))*. + +## choose + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| input | text | required | Current user request or local decision | +| options | list | required | Small list of registered option names | +| model | any | None | Existing provider model identifier | +| repair | bool | True | Allow one format-only repair attempt | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Verified choice result, or explicit failure | + +Only ask for the option name. A failed first parse can receive one short +format correction; never silently select the nearest-looking option. + +We retain **opts = [Encode allowed values](json.stringify(value=`options`))**. +We retain **prompt = "Choose exactly one of these options. Return its name only, no explanation:\n" + opts + "\nInput:\n" + input**. +We retain **reply = [Ask the model once](llm.ask(prompt=`prompt`, model=`model`))**. +We retain **parsed = [Validate the model reply](parse_choice(reply=`reply`, options=`options`))**. +We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. +1. ok + Return *parsed*. +2. `repair` + We retain **fix = "Your answer was not an exact allowed option. Return only ONE option name from:\n" + opts**. + We retain **again = [Retry the format only once](llm.ask(prompt=`fix`, model=`model`))**. + Return *[Validate the repaired reply](parse_choice(reply=`again`, options=`options`))*. +3. * + Return *parsed*. + +## parallel + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| tasks | list | required | Existing .mq.md file tasks with arguments | +| limit | number | 2 | Maximum simultaneously running tasks | +| timeout_ms | number | 30000 | Execution timeout in milliseconds | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | list | Ordered child outcomes, including failures | + +Reuse the built-in subtask scheduler. Each child document returns via its +# main, and successful siblings remain visible if another child fails. + +Return *[Run bounded Marqdo document tasks](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))*. From 7fdd97f675e25d0bba358d6352151c175931f0df Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:30:33 +0800 Subject: [PATCH 04/66] feat(agent): classify invalid model output and bound local recovery --- plugins/agent/src/error.rs | 41 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 39 insertions(+), 2 deletions(-) diff --git a/plugins/agent/src/error.rs b/plugins/agent/src/error.rs index 5223b82..d9a6317 100644 --- a/plugins/agent/src/error.rs +++ b/plugins/agent/src/error.rs @@ -82,6 +82,10 @@ pub fn decide_retry(args: &Value) -> Result { .get("max_arg_repairs") .and_then(|v| v.as_u64()) .unwrap_or(1) as u32; + let max_output_repair = args + .get("max_output_repairs") + .and_then(|v| v.as_u64()) + .unwrap_or(1) as u32; let effect_class = args .get("effect_class") .and_then(|v| v.as_str()) @@ -145,6 +149,12 @@ pub fn decide_retry(args: &Value) -> Result { "invalid_arguments" if recovery == "repair_args" && attempts < max_arg_repair => Ok( decision("repair_args", "one_arg_repair", attempts, max_arg_repair), ), + "invalid_output" if recovery == "repair_output" && attempts < max_output_repair => Ok( + decision("repair_output", "one_format_repair", attempts, max_output_repair), + ), + "context_overflow" if recovery == "compact_context" && attempts == 0 => Ok( + decision("compact_context", "one_bounded_compaction", attempts, 1), + ), "auth" | "forbidden" | "policy_denied" => Ok(decision( "needs_input", category, @@ -172,13 +182,17 @@ fn decision(action: &str, reason: &str, attempts: u32, max_attempts: u32) -> Val "reason": reason, "attempts_used": attempts, "max_attempts": max_attempts, - "auto": matches!(action, "retry_step" | "repair_args"), + "auto": matches!(action, "retry_step" | "repair_args" | "repair_output" | "compact_context"), }) } fn infer_category(code: &str) -> &'static str { let c = code.to_ascii_lowercase(); - if c.contains("timeout") || c.contains("429") || c.contains("5xx") || c.contains("connect") { + if c.contains("context_overflow") || c.contains("context_length") { + "context_overflow" + } else if c.contains("invalid_choice") || c.contains("invalid_output") { + "invalid_output" + } else if c.contains("timeout") || c.contains("429") || c.contains("5xx") || c.contains("connect") { "transient" } else if c.contains("schema") || c.contains("argument") { "invalid_arguments" @@ -212,6 +226,8 @@ fn default_recovery(category: &str, effect_state: &str) -> &'static str { match category { "transient" => "retry_step", "invalid_arguments" => "repair_args", + "invalid_output" => "repair_output", + "context_overflow" => "compact_context", "auth" | "forbidden" | "policy_denied" | "needs_input" => "needs_input", "budget_exhausted" => "return_partial", "cancelled" => "stop", @@ -259,6 +275,27 @@ mod tests { assert_eq!(d["auto"], false); } + #[test] + fn output_repair_is_bounded_and_read_only() { + let err = make_error(&json!({"code": "model.invalid_choice"})).unwrap(); + assert_eq!(err["category"], "invalid_output"); + let first = decide_retry(&json!({"error": err, "attempts": 0})).unwrap(); + assert_eq!(first["action"], "repair_output"); + let next = decide_retry(&json!({"error": err, "attempts": 1})).unwrap(); + assert_eq!(next["action"], "stop"); + let write = decide_retry(&json!({ + "error": err, "attempts": 0, "effect_class": "write" + })).unwrap(); + assert_eq!(write["action"], "manual_review"); + } + + #[test] + fn compaction_is_not_an_unbounded_model_loop() { + let err = make_error(&json!({"code": "model.context_overflow"})).unwrap(); + assert_eq!(decide_retry(&json!({"error": err, "attempts": 0})).unwrap()["action"], "compact_context"); + assert_eq!(decide_retry(&json!({"error": err, "attempts": 1})).unwrap()["action"], "stop"); + } + #[test] fn fingerprint_loop_stops() { let err = make_error(&json!({"code": "tool.timeout"})).unwrap(); From d88ed274ed1a9368ef828909dcca3e388f240e19 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:30:49 +0800 Subject: [PATCH 05/66] feat(ai): expose short checkpoint and bounded recovery functions --- ext/ai/recovery.mq.md | 64 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 ext/ai/recovery.mq.md diff --git a/ext/ai/recovery.mq.md b/ext/ai/recovery.mq.md new file mode 100644 index 0000000..c38867e --- /dev/null +++ b/ext/ai/recovery.mq.md @@ -0,0 +1,64 @@ +--- +markup: occlusion +title: AI recovery — safe defaults for short SKILL functions +description: Reuse the native error policy, durable checkpoints and effect ledger. +import: + agent: ext/ai/agent.mq.md +--- + +Error handling belongs to Marqdo, not the model's prompt. The native policy +never blindly repeats uncertain writes. Every resume must revalidate the +current permission and source revision; a saved checkpoint is not authorization. + +## decide + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| error | map | required | Structured AgentErrorV1 | +| attempts | number | 0 | Number of attempts already made | +| effect_class | text | "read" | Declared tool effect | +| cancelled | bool | False | Parent cancellation status | +| fingerprint_repeats | number | 0 | Identical failures without new evidence | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Safe recovery action with budget | + +This returns an action, not an automatic retry or permission to execute. For +write or unknown effect, consult the effect ledger before taking another step. + +Return *[Select a bounded recovery action](agent.error_decide_retry(error=`error`, attempts=`attempts`, effect_class=`effect_class`, cancelled=`cancelled`, fingerprint_repeats=`fingerprint_repeats`))*. + +## save + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Stable logical run ID | +| task | any | None | Current task or user request | +| status | text | "waiting_input" | Current run status | +| effect_ledger_watermark | any | None | Durable ledger boundary if available | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | CheckpointV2 write result | + +Use the existing atomic checkpoint writer. When ledger evidence is absent, +a resumed writer requires manual review rather than automatic repetition. +This function saves metadata; it does not suspend a Rust execution frame. + +Return *[Save a versioned checkpoint](agent.resume_save(id=`id`, task=`task`, status=`status`, checkpoint_v2=True, effect_ledger_watermark=`effect_ledger_watermark`))*. + +## load + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Previously saved logical run ID | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Checkpoint or missing/unsafe recovery status | + +Loading a checkpoint does not execute any saved step. The caller must inspect +recovery_mode and write_auto_resume before dispatching any effectful operation. + +Return *[Inspect the saved checkpoint](agent.resume_load(id=`id`))*. From eed4f05ea465a5497ff16ecb54b79ceaa3a11a71 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:31:14 +0800 Subject: [PATCH 06/66] ci(agent): test native parser and check the new Marqdo flow modules --- .github/workflows/executable-knowledge.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml index 2dcecd5..b44ef1f 100644 --- a/.github/workflows/executable-knowledge.yml +++ b/.github/workflows/executable-knowledge.yml @@ -15,6 +15,12 @@ jobs: run: | cargo build -p marqdo_plugin_agent --locked cargo build -p marqdo_plugin_llm --locked + - name: Native agent choice and bounded recovery unit tests + run: cargo test -p marqdo_plugin_agent --locked + - name: Check short AI flow documents + run: | + cargo run --locked -- check ext/ai/flow.mq.md + cargo run --locked -- check ext/ai/recovery.mq.md - name: Workbench contracts (M00–M06 / F-subset) run: cargo test --test workbench_contracts --locked - name: Offline executable-knowledge gate From e64f6b23b4eae5e78756e69d945f5d833bd82f64 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:32:04 +0800 Subject: [PATCH 07/66] fix(ai): use valid Marqdo branch expressions and literal main reference --- ext/ai/flow.mq.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index 123f4a4..972f722 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -28,7 +28,7 @@ Parsing accepts one exact name, a labeled name, a fenced name or a 1-based index. Ambiguous prose fails closed. Parsing never runs a tool or SKILL. We retain **p = [Locate the installed agent plugin](plugin.native_path(name="agent"))**. -1. p +1. `p` We **[Load the agent plugin](plugin.load(path=`p`))**. 2. * Return *[Missing native parser](json.parse(text="{\"ok\":false,\"status\":\"unavailable\",\"value\":null}"))*. @@ -56,7 +56,7 @@ We retain **prompt = "Choose exactly one of these options. Return its name only, We retain **reply = [Ask the model once](llm.ask(prompt=`prompt`, model=`model`))**. We retain **parsed = [Validate the model reply](parse_choice(reply=`reply`, options=`options`))**. We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. -1. ok +1. `ok` Return *parsed*. 2. `repair` We retain **fix = "Your answer was not an exact allowed option. Return only ONE option name from:\n" + opts**. @@ -78,6 +78,6 @@ We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. | result | list | Ordered child outcomes, including failures | Reuse the built-in subtask scheduler. Each child document returns via its -# main, and successful siblings remain visible if another child fails. +`# main`, and successful siblings remain visible if another child fails. Return *[Run bounded Marqdo document tasks](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))*. From b0ee958fcf131f8282645df79f29cb34f6fa9fb1 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:32:48 +0800 Subject: [PATCH 08/66] feat(ai): add explicit small-model file/class/function context pack --- ext/ai/context.mq.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 ext/ai/context.mq.md diff --git a/ext/ai/context.mq.md b/ext/ai/context.mq.md new file mode 100644 index 0000000..a99ef71 --- /dev/null +++ b/ext/ai/context.mq.md @@ -0,0 +1,41 @@ +--- +markup: occlusion +title: AI context — short, explicit source scopes +description: Pack user input and caller-provided file/class/function excerpts. +import: + agent: ext/ai/agent.mq.md +--- + +Pass only the documentation that the next model decision needs. The supplied +file/class/function snippets are data; they do not execute as Marqdo source. +A future compiler-backed selector can supply these arguments from AST spans. +This helper does not yet infer class/function scopes automatically. + +## pack + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| user | text | required | Latest user input | +| file | text | "" | File-level description excerpt | +| class | text | "" | Current class excerpt | +| function | text | "" | Current function excerpt | +| budget_tokens | number | 2048 | Small-model context budget | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Bounded ContextPackV2 and compaction evidence | + +Keep the latest request and current function first. Low-priority file context +may be dropped under pressure; any important constraint must be in a retained +field, not in a discardable tool transcript. + +`items` = + +| @ | origin | trust | priority | text | retain | +|---|---|---|---|---|---| +| 1 | user | user | 0 | `user` | True | +| 2 | function | unknown | 1 | `function` | True | +| 3 | class | unknown | 2 | `class` | False | +| 4 | file | unknown | 3 | `file` | False | + +Return *[Pack the supplied scopes and compact redundant context](agent.context_pack_compact(items=`items`, budget_tokens=`budget_tokens`, goal=`user`))*. From bdedf3ecd86efc19768274489d3846830b5cbfe8 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:32:55 +0800 Subject: [PATCH 09/66] ci(ai): include scoped context pack in syntax gates --- .github/workflows/executable-knowledge.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml index b44ef1f..6d3882d 100644 --- a/.github/workflows/executable-knowledge.yml +++ b/.github/workflows/executable-knowledge.yml @@ -21,6 +21,7 @@ jobs: run: | cargo run --locked -- check ext/ai/flow.mq.md cargo run --locked -- check ext/ai/recovery.mq.md + cargo run --locked -- check ext/ai/context.mq.md - name: Workbench contracts (M00–M06 / F-subset) run: cargo test --test workbench_contracts --locked - name: Offline executable-knowledge gate From f56deffefeafd6a5c1bee15cf97fc906fdba4b6d Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:33:28 +0800 Subject: [PATCH 10/66] test(agent): isolate EffectLedger tests without process-global cwd races --- plugins/agent/src/effects.rs | 64 +++++++++++++++++------------------- 1 file changed, 30 insertions(+), 34 deletions(-) diff --git a/plugins/agent/src/effects.rs b/plugins/agent/src/effects.rs index bd80c0f..8c4ff03 100644 --- a/plugins/agent/src/effects.rs +++ b/plugins/agent/src/effects.rs @@ -425,12 +425,16 @@ fn fnv64(s: &str) -> u64 { mod tests { use super::*; + // Avoid process-global set_current_dir: Rust executes tests concurrently. + // Keep each ledger in its own repository-relative, unique directory. + static SCRATCH_SEQ: std::sync::atomic::AtomicU64 = + std::sync::atomic::AtomicU64::new(0); + fn scratch(tag: &str) -> PathBuf { - let dir = std::env::temp_dir().join(format!( + let seq = SCRATCH_SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed); + let dir = PathBuf::from("target").join(format!( "mq-effects-{}-{}-{}", - tag, - std::process::id(), - now_rfc3339().replace(':', "") + tag, std::process::id(), seq )); let _ = fs::remove_dir_all(&dir); fs::create_dir_all(&dir).unwrap(); @@ -440,14 +444,13 @@ mod tests { #[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 ledger_dir = dir.join("led").to_string_lossy().to_string(); let a = effects_prepare(&json!({ "operation_id": "op1", "idempotency_key": "idem1", "args_digest": "sha256:a", "effect_class": "write", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run1", })) .unwrap(); @@ -458,7 +461,7 @@ mod tests { "operation_id": "op1", "idempotency_key": "idem1", "args_digest": "sha256:a", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })) .unwrap(); assert_eq!(again["deduped"], true); @@ -467,43 +470,41 @@ mod tests { "operation_id": "op2", "idempotency_key": "idem1", "args_digest": "sha256:b", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })); 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(); + let ledger_dir = dir.join("led").to_string_lossy().to_string(); effects_prepare(&json!({ "operation_id": "op_w", "idempotency_key": "idem_w", "args_digest": "sha256:w", "effect_class": "write", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run1", })) .unwrap(); effects_transition(&json!({ "operation_id": "op_w", "state": "started", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })) .unwrap(); // Crash window: unknown — write auto-resume must stay closed. effects_transition(&json!({ "operation_id": "op_w", "state": "unknown", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })) .unwrap(); let wm1 = effects_watermark(&json!({ - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run1", })) .unwrap(); @@ -513,12 +514,12 @@ mod tests { effects_reconcile(&json!({ "operation_id": "op_w", "outcome": "committed", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "result_ref": "receipt:1", })) .unwrap(); let wm2 = effects_watermark(&json!({ - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run1", })) .unwrap(); @@ -526,7 +527,6 @@ mod tests { 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); } @@ -535,32 +535,31 @@ mod tests { // Write "succeeds" locally only after reconcile; retry while unknown must not // look write_auto_resume_safe (MA-T03 watermark gate). let dir = scratch("mat03"); - let prev = std::env::current_dir().unwrap(); - std::env::set_current_dir(&dir).unwrap(); + let ledger_dir = dir.join("led").to_string_lossy().to_string(); effects_prepare(&json!({ "operation_id": "op_kill", "idempotency_key": "run|s|write_probe|sha256-lite:1", "args_digest": "sha256-lite:1", "effect_class": "write", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run_kill", })) .unwrap(); effects_transition(&json!({ "operation_id": "op_kill", "state": "started", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })) .unwrap(); // Crash before commit: effects_transition(&json!({ "operation_id": "op_kill", "state": "unknown", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })) .unwrap(); let wm = effects_watermark(&json!({ - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run_kill", })) .unwrap(); @@ -572,7 +571,7 @@ mod tests { "idempotency_key": "run|s|write_probe|sha256-lite:1", "args_digest": "sha256-lite:1", "effect_class": "write", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run_kill", })) .unwrap(); @@ -582,42 +581,39 @@ mod tests { effects_reconcile(&json!({ "operation_id": "op_kill", "outcome": "committed", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "result_ref": "effect:op_kill", })) .unwrap(); let wm2 = effects_watermark(&json!({ - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run_kill", })) .unwrap(); assert_eq!(wm2["write_auto_resume_safe"], true); assert_eq!(wm2["pending_writes"], 0); - 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(); + let ledger_dir = dir.join("led").to_string_lossy().to_string(); effects_prepare(&json!({ "operation_id": "op_x", "idempotency_key": "idem_x", "args_digest": "sha256:x", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })) .unwrap(); let err = effects_transition(&json!({ "operation_id": "op_x", "state": "committed", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })) .unwrap_err(); assert!(err.contains("illegal transition")); - std::env::set_current_dir(prev).unwrap(); let _ = fs::remove_dir_all(&dir); } } From 9564dff777d1aca972ae4af4679c40021efad8fc Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:34:13 +0800 Subject: [PATCH 11/66] docs(ai): link the new native flow, context and recovery modules --- ext/ai/index.mq.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/ext/ai/index.mq.md b/ext/ai/index.mq.md index 70ac986..197615e 100644 --- a/ext/ai/index.mq.md +++ b/ext/ai/index.mq.md @@ -9,7 +9,11 @@ Start here to choose an AI task. [Model calls](llm.mq.md) own prompts, model con stream collection and usage; [provider adapters](llm/index.mq.md) describe OpenAI-compatible and Ollama requests. [Agents](agent.mq.md) own call-site context, the explicit tool registry, policy routing, observations, workbook planning and continuation. [CoW trials](sandbox.mq.md) -own isolated file changes and promotion. [Step routing](policies/step-route.mq.md) is readable +own isolated file changes and promotion. [Native flow](flow.mq.md) provides short, verified model choices and bounded document +concurrency; [context](context.mq.md) packs explicit source scopes; [recovery](recovery.mq.md) +uses the native error policy and versioned checkpoints. These are lightweight +interfaces, not a second agent runtime. +[Step routing](policies/step-route.mq.md) is readable policy data, not a second agent language. Chinese users can start at [索引](索引.mq.md). Begin with this offline stream example; it does not request credentials, install a plugin or From 3613ed7c4eb12225f129e59caabe323bc0be5310 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:36:26 +0800 Subject: [PATCH 12/66] fix(ai): declare function parameters in Marqdo prose syntax --- ext/ai/flow.mq.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index 972f722..3741f8c 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -24,6 +24,8 @@ Only the requested function and its inputs need to be in the model prompt. |---|---|---| | result | map | {ok,value,status} or {ok:false,error} | +Use `reply`, `options` as the inputs for this operation. + Parsing accepts one exact name, a labeled name, a fenced name or a 1-based index. Ambiguous prose fails closed. Parsing never runs a tool or SKILL. @@ -48,6 +50,8 @@ Return *[Parse and verify the choice](agent_choice_parse(reply=`reply`, options= |---|---|---| | result | map | Verified choice result, or explicit failure | +Use `input`, `options`, `model`=None, `repair`=True as the inputs for this operation. + Only ask for the option name. A failed first parse can receive one short format correction; never silently select the nearest-looking option. @@ -77,6 +81,8 @@ We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. |---|---|---| | result | list | Ordered child outcomes, including failures | +Use `tasks`, `limit`=2, `timeout_ms`=30000 as the inputs for this operation. + Reuse the built-in subtask scheduler. Each child document returns via its `# main`, and successful siblings remain visible if another child fails. From a82b6fdde1c706cd2becc3d0191a8255f2835418 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:36:28 +0800 Subject: [PATCH 13/66] fix(ai): declare function parameters in Marqdo prose syntax --- ext/ai/context.mq.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ext/ai/context.mq.md b/ext/ai/context.mq.md index a99ef71..c564cc5 100644 --- a/ext/ai/context.mq.md +++ b/ext/ai/context.mq.md @@ -25,6 +25,8 @@ This helper does not yet infer class/function scopes automatically. |---|---|---| | result | map | Bounded ContextPackV2 and compaction evidence | +Use `user`, `file`="", `class`="", `function`="", `budget_tokens`=2048 as the inputs for this operation. + Keep the latest request and current function first. Low-priority file context may be dropped under pressure; any important constraint must be in a retained field, not in a discardable tool transcript. From a0c779e022e42b862b3da566692786285a04c45b Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:36:31 +0800 Subject: [PATCH 14/66] fix(ai): declare function parameters in Marqdo prose syntax --- ext/ai/recovery.mq.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/ext/ai/recovery.mq.md b/ext/ai/recovery.mq.md index c38867e..afe2e47 100644 --- a/ext/ai/recovery.mq.md +++ b/ext/ai/recovery.mq.md @@ -24,6 +24,8 @@ current permission and source revision; a saved checkpoint is not authorization. |---|---|---| | result | map | Safe recovery action with budget | +Use `error`, `attempts`=0, `effect_class`="read", `cancelled`=False, `fingerprint_repeats`=0 as the inputs for this operation. + This returns an action, not an automatic retry or permission to execute. For write or unknown effect, consult the effect ledger before taking another step. @@ -42,6 +44,8 @@ Return *[Select a bounded recovery action](agent.error_decide_retry(error=`error |---|---|---| | result | map | CheckpointV2 write result | +Use `id`, `task`=None, `status`="waiting_input", `effect_ledger_watermark`=None as the inputs for this operation. + Use the existing atomic checkpoint writer. When ledger evidence is absent, a resumed writer requires manual review rather than automatic repetition. This function saves metadata; it does not suspend a Rust execution frame. @@ -58,6 +62,8 @@ Return *[Save a versioned checkpoint](agent.resume_save(id=`id`, task=`task`, st |---|---|---| | result | map | Checkpoint or missing/unsafe recovery status | +Use `id` as the inputs for this operation. + Loading a checkpoint does not execute any saved step. The caller must inspect recovery_mode and write_auto_resume before dispatching any effectful operation. From 0d9bd99fc012474adc976c3fd6e6b0ad0a9977e2 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:36:52 +0800 Subject: [PATCH 15/66] feat(agent): add Markdown heading-scoped bounded file/class/function prompt projection with tests --- plugins/agent/src/context_scope.rs | 201 +++++++++++++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 plugins/agent/src/context_scope.rs diff --git a/plugins/agent/src/context_scope.rs b/plugins/agent/src/context_scope.rs new file mode 100644 index 0000000..bb9a148 --- /dev/null +++ b/plugins/agent/src/context_scope.rs @@ -0,0 +1,201 @@ +//! Markdown-heading-backed, bounded context projection for Marqdo SKILLs. +//! This is source selection, not execution: quoted text never becomes tool authority. +//! Markdown events ignore fenced-code headings; ambiguous functions fail closed. + +use pulldown_cmark::{Event, HeadingLevel, Parser, Tag, TagEnd}; +use serde_json::{json, Value}; + +#[derive(Clone, Debug)] +struct Section { + level: u8, + title: String, + start: usize, +} + +fn level_num(h: HeadingLevel) -> u8 { + match h { + HeadingLevel::H1 => 1, + HeadingLevel::H2 => 2, + HeadingLevel::H3 => 3, + HeadingLevel::H4 => 4, + HeadingLevel::H5 => 5, + HeadingLevel::H6 => 6, + } +} + +fn headings(source: &str) -> Vec
{ + let mut out = Vec::new(); + let mut pending: Option
= None; + for (event, range) in Parser::new(source).into_offset_iter() { + match event { + Event::Start(Tag::Heading { level, .. }) => { + pending = Some(Section { + level: level_num(level), + title: String::new(), + start: range.start, + }); + } + Event::Text(text) | Event::Code(text) => { + if let Some(section) = pending.as_mut() { + section.title.push_str(&text); + } + } + Event::End(TagEnd::Heading(_)) => { + if let Some(mut section) = pending.take() { + section.title = section.title.trim().to_string(); + out.push(section); + } + } + _ => {} + } + } + out +} + +fn class_for(headings: &[Section], index: usize) -> Option<&str> { + headings[..index] + .iter() + .rev() + .find(|h| h.level == 1) + .map(|h| h.title.as_str()) +} + +fn frontmatter_end(source: &str) -> usize { + if !source.starts_with("---\n") { + return 0; + } + let mut pos = 4; + for line in source[4..].split_inclusive('\n') { + pos += line.len(); + if line.trim() == "---" { + return pos; + } + } + 0 +} + +fn truncate_chars(text: &str, max_chars: usize) -> (&str, bool) { + let Some((end, _)) = text.char_indices().nth(max_chars) else { + return (text, false); + }; + (&text[..end], true) +} + +pub fn project(args: &Value) -> Result { + let source = match args.get("source").and_then(Value::as_str) { + Some(s) => s.to_string(), + None => crate::host_query_json("module_source")? + .as_str() + .ok_or_else(|| "module_source unavailable".to_string())? + .to_string(), + }; + let scope = args.get("scope").and_then(Value::as_str).unwrap_or("function"); + let class = args.get("class").and_then(Value::as_str); + let function = args.get("function").and_then(Value::as_str); + let maximum = args + .get("max_chars") + .and_then(Value::as_u64) + .unwrap_or(1600) + .clamp(32, 16000) as usize; + let marks = headings(&source); + let results: Vec<(usize, usize)> = match scope { + "file" => { + let end = marks.first().map_or(source.len(), |h| h.start); + let start = frontmatter_end(&source).min(end); + vec![(start, end)] + } + "class" | "function" | "tool" => { + let level = match scope { + "class" => 1, + "function" => 2, + _ => 3, + }; + let target = if level == 1 { class } else { function }; + let wanted = target.ok_or_else(|| format!("{scope} selector required"))?; + marks + .iter() + .enumerate() + .filter(|(i, h)| { + h.level == level + && h.title == wanted + && (level == 1 || class.is_none() || class_for(&marks, *i) == class) + }) + .map(|(i, h)| { + let end = marks[i + 1..] + .iter() + .find(|next| next.level <= level) + .map_or(source.len(), |next| next.start); + let end = if level == 1 { + marks[i + 1..] + .iter() + .find(|next| next.level <= 2) + .map_or(end, |next| next.start) + } else { + end + }; + (h.start, end) + }) + .collect() + } + _ => return Err("scope must be file, class, function or tool".to_string()), + }; + if results.len() != 1 { + return Ok(json!({ + "ok": false, + "status": if results.is_empty() { "not_found" } else { "ambiguous" }, + "scope": scope, + "matches": results.len(), + "text": null + })); + } + let (start, end) = results[0]; + let (slice, truncated) = truncate_chars(source[start..end].trim(), maximum); + let line_start = source[..start].bytes().filter(|c| *c == b'\n').count() + 1; + Ok(json!({ + "ok": true, "status": "accepted", "scope": scope, + "text": slice, "truncated": truncated, + "start_byte": start, "end_byte": end, + "start_line": line_start, + "source_kind": "markdown_headings" + })) +} + +#[cfg(test)] +mod tests { + use super::*; + + const DOC: &str = "---\ntitle: example\n---\nEntry instructions.\n\n# main\nClass instructions.\n\n## route\nReal body.\n```md\n## route\nfake\n```\n\n## other\nOther body.\n\n# helper\nHelper prose.\n\n## route\nSecond body.\n"; + + #[test] + fn scope_is_bounded_and_fenced_headings_ignored() { + let v = project(&json!({"source": DOC, "scope": "function", "class": "main", "function": "route"})).unwrap(); + assert_eq!(v["ok"], true); + assert!(v["text"].as_str().unwrap().contains("Real body.")); + assert!(v["text"].as_str().unwrap().contains("fake")); + assert!(!v["text"].as_str().unwrap().contains("Other body.")); + assert!(!v["text"].as_str().unwrap().contains("Second body.")); + } + + #[test] + fn ambiguous_function_fails_closed() { + let v = project(&json!({"source": DOC, "scope": "function", "function": "route"})).unwrap(); + assert_eq!(v["status"], "ambiguous"); + assert_eq!(v["text"], Value::Null); + } + + #[test] + fn file_scope_removes_frontmatter_and_class_prose_excludes_functions() { + let a = project(&json!({"source": DOC, "scope": "file"})).unwrap(); + assert_eq!(a["text"], "Entry instructions."); + let b = project(&json!({"source": DOC, "scope": "class", "class": "main"})).unwrap(); + assert!(b["text"].as_str().unwrap().contains("Class instructions.")); + assert!(!b["text"].as_str().unwrap().contains("Real body.")); + } + + #[test] + fn unicode_truncation_does_not_split_characters() { + let v = project(&json!({"source": "汉".repeat(100), "scope": "file", "max_chars": 32})).unwrap(); + assert_eq!(v["text"].as_str().unwrap().chars().count(), 32); + assert_eq!(v["truncated"], true); + } +} From 393558ca971355466adb2702334a2516c1a5d0bf Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:36:59 +0800 Subject: [PATCH 16/66] feat(agent): register scoped context projection in native plugin --- plugins/agent/Cargo.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/plugins/agent/Cargo.toml b/plugins/agent/Cargo.toml index 663e5b8..4965693 100644 --- a/plugins/agent/Cargo.toml +++ b/plugins/agent/Cargo.toml @@ -13,4 +13,5 @@ crate-type = ["cdylib"] [dependencies] marqdo-plugin-sdk = { path = "../../crates/marqdo-plugin-sdk" } serde_json = "1" +pulldown-cmark = "0.12" chrono = { version = "0.4", default-features = false, features = ["clock", "std"] } From f63b7ef48d869ce58473aac2b7bacf4755b104c8 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:37:02 +0800 Subject: [PATCH 17/66] feat(agent): register scoped context projection in native plugin --- plugins/agent/src/lib.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 23783c6..b40587e 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -2,6 +2,7 @@ mod choice; mod context_pack; +mod context_scope; mod corpus; mod effects; mod eng; @@ -836,6 +837,7 @@ kb_ffi!(agent_resume_load, resume::resume_load, "agent_resume_load"); kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear"); kb_ffi!(agent_resume_list, resume::resume_list, "agent_resume_list"); kb_ffi!(agent_choice_parse, choice::parse_choice, "agent_choice_parse"); +kb_ffi!(agent_context_scope, context_scope::project, "agent_context_scope"); kb_ffi!(agent_error_make, error::make_error, "agent_error_make"); kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry"); kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register"); @@ -966,6 +968,7 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_resume_clear", "id,resume_dir", agent_resume_clear), ("agent_resume_list", "resume_dir", agent_resume_list), ("agent_choice_parse", "reply,options", agent_choice_parse), + ("agent_context_scope", "source,scope,class,function", agent_context_scope), ("agent_error_make", "code,message,category", agent_error_make), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_tools_register", "spec,specs", agent_tools_register), From 905a67df32afa6595f457c1c1e88b64fa696db25 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:37:18 +0800 Subject: [PATCH 18/66] feat(ai): expose native Markdown scope selection to Marqdo authors --- ext/ai/context.mq.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/ext/ai/context.mq.md b/ext/ai/context.mq.md index c564cc5..3905067 100644 --- a/ext/ai/context.mq.md +++ b/ext/ai/context.mq.md @@ -4,6 +4,8 @@ title: AI context — short, explicit source scopes description: Pack user input and caller-provided file/class/function excerpts. import: agent: ext/ai/agent.mq.md + plugin: lib/plugin.mq.md + json: lib/json.mq.md --- Pass only the documentation that the next model decision needs. The supplied @@ -41,3 +43,32 @@ field, not in a discardable tool transcript. | 4 | file | unknown | 3 | `file` | False | Return *[Pack the supplied scopes and compact redundant context](agent.context_pack_compact(items=`items`, budget_tokens=`budget_tokens`, goal=`user`))*. + + +## scope + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| scope | text | "function" | file / class / function / tool | +| class | text | None | Class heading for disambiguation | +| function | text | None | Function/tool heading | +| source | text | None | Source override; otherwise current entry module | +| max_chars | number | 1600 | Maximum Unicode characters | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Exact source excerpt, line range, or explicit ambiguity | + +Use `scope`="function", `class`=None, `function`=None, `source`=None, `max_chars`=1600 as the inputs for this operation. + +The native selector respects Markdown headings and ignores fenced-code heading +lookalikes. Repeated function names require a class; missing/ambiguous scopes +return an error value, never an unrelated or whole-file fallback. + +We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load native agent plugin](plugin.load(path=`p`))**. +2. * + Return *[No native parser available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\",\"text\":null}"))*. + +Return *[Project the requested document scope](agent_context_scope(source=`source`, scope=`scope`, class=`class`, function=`function`, max_chars=`max_chars`))*. From afe31cb2a8f879877a0d52a54056ea0de7feb0b8 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:37:35 +0800 Subject: [PATCH 19/66] feat(agent): durable user-input gate with idempotent reply, revision and session checks --- plugins/agent/src/input.rs | 248 +++++++++++++++++++++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 plugins/agent/src/input.rs diff --git a/plugins/agent/src/input.rs b/plugins/agent/src/input.rs new file mode 100644 index 0000000..8100f23 --- /dev/null +++ b/plugins/agent/src/input.rs @@ -0,0 +1,248 @@ +//! Durable input gates for document-native SKILLs. +//! Pausing is a committed *step boundary*, not serialization of a Rust stack. +//! The caller resumes the next documented step with the saved answer. + +use std::fs::{self, OpenOptions}; +use std::path::PathBuf; +use serde_json::{json, Value}; + +use crate::resume; + +struct GateLock(PathBuf); +impl Drop for GateLock { + fn drop(&mut self) { + let _ = fs::remove_file(&self.0); + } +} + +fn text_arg<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> { + args.get(key) + .and_then(Value::as_str) + .filter(|s| !s.is_empty()) + .ok_or_else(|| format!("missing text `{key}`")) +} + +fn valid_id(s: &str) -> bool { + !s.is_empty() + && s.len() <= 100 + && s.bytes().all(|c| c.is_ascii_alphanumeric() || c == b'-' || c == b'_') +} + +fn root(args: &Value) -> Result { + let name = args + .get("resume_dir") + .and_then(Value::as_str) + .unwrap_or(".marqdo/agent-resume"); + let path = PathBuf::from(name); + if path.is_absolute() + || path.components().any(|part| matches!(part, std::path::Component::ParentDir)) + { + return Err("resume_dir must be a relative path without '..'".to_string()); + } + fs::create_dir_all(&path).map_err(|e| format!("input gate mkdir: {e}"))?; + Ok(path) +} + +fn lock(args: &Value, id: &str) -> Result { + if !valid_id(id) { + return Err("input gate id must be 1..=100 ASCII letters, numbers, '_' or '-'".into()); + } + let path = root(args)?.join(format!("{id}.input-lock")); + OpenOptions::new() + .write(true) + .create_new(true) + .open(&path) + .map_err(|e| format!("input gate is busy or needs reconciliation: {e}"))?; + Ok(GateLock(path)) +} + +fn options(args: &Value) -> Result { + let choices = args.get("options").and_then(Value::as_array) + .ok_or_else(|| "options must be a list of 1..=32 short labels".to_string())?; + if choices.is_empty() || choices.len() > 32 { + return Err("options must contain 1..=32 choices".into()); + } + for v in choices { + let Some(s) = v.as_str() else { + return Err("every option must be text".into()); + }; + if s.is_empty() || s.len() > 256 { + return Err("each option must contain 1..=256 bytes".into()); + } + } + let empty = crate::choice::parse_choice(&json!({ + "options": choices, "reply": "__invalid_choice_probe__" + }))?; + // The parser checks duplicates and option size; the probe must not be accepted. + if empty["ok"] == true { + return Err("invalid reserved choice option".into()); + } + Ok(Value::Array(choices.to_vec())) +} + +/// Create a durable waiting-input checkpoint. Repeated open never resets a +/// previously answered gate. No external effect is performed. +pub fn input_open(args: &Value) -> Result { + let id = text_arg(args, "id")?; + let _lock = lock(args, id)?; + let labels = options(args)?; + let query = text_arg(args, "question")?; + let version = text_arg(args, "source_revision")?; + let read_args = json!({"id": id, "resume_dir": args.get("resume_dir")}); + let existing = resume::resume_load(&read_args)?; + if existing["found"] == true { + let meta = &existing["meta"]; + let same = meta["question"] == query + && meta["options"] == labels + && meta["source_revision"] == version + && meta["session_id"] == args.get("session_id").unwrap_or(&Value::Null) + && meta["principal_ref"] == args.get("principal_ref").unwrap_or(&Value::Null); + if same && existing["ok"] == true { + let status = existing["status"].as_str().unwrap_or("unknown"); + return Ok(json!({ + "ok": true, "id": id, "status": status, + "value": existing["result"], "reused": true, + "question": query, "options": labels + })); + } + return Ok(json!({"ok":false,"id":id,"status":"conflict", + "error":{"code":"input.stale_or_reused_gate"}})); + } + let saved = resume::resume_save(&json!({ + "id": id, "resume_dir": args.get("resume_dir"), + "checkpoint_v2": true, + "status": "waiting_input", + "task": query, + "meta": { + "question": query, + "options": labels, + "source_revision": version, + "session_id": args.get("session_id").unwrap_or(&Value::Null), + "principal_ref": args.get("principal_ref").unwrap_or(&Value::Null), + "freeform": args.get("freeform").and_then(Value::as_bool).unwrap_or(true) + } + }))?; + if saved["ok"] != true { + return Err("unable to save input checkpoint".into()); + } + Ok(json!({"ok": true, "id":id, "status":"waiting_input", "value":null, + "question":query,"options":labels,"reused":false})) +} + +/// Resume a specific gate with a user response. Only a committed answer can be +/// replayed: different duplicate replies conflict instead of re-triggering work. +pub fn input_resume(args: &Value) -> Result { + let id = text_arg(args, "id")?; + let _lock = lock(args, id)?; + let reply = text_arg(args, "reply")?; + if reply.len() > 4096 { + return Err("input reply must not exceed 4096 bytes".into()); + } + let version = text_arg(args, "source_revision")?; + let read_args = json!({"id": id, "resume_dir": args.get("resume_dir")}); + let existing = resume::resume_load(&read_args)?; + if existing["ok"] != true || existing["schema"] != "CheckpointV2" { + return Ok(json!({"ok":false,"status":"not_found_or_corrupt","id":id})); + } + let meta = &existing["meta"]; + if meta["source_revision"] != version + || meta["session_id"] != *args.get("session_id").unwrap_or(&Value::Null) + || meta["principal_ref"] != *args.get("principal_ref").unwrap_or(&Value::Null) + { + return Ok(json!({"ok":false,"status":"conflict","id":id, + "error":{"code":"input.scope_or_revision_changed"}})); + } + if existing["status"] == "resumed" { + if existing["result"] == reply { + return Ok(json!({"ok":true,"status":"resumed","id":id, + "value":reply,"reused":true})); + } + return Ok(json!({"ok":false,"status":"conflict","id":id, + "error":{"code":"input.already_answered"}})); + } + if existing["status"] != "waiting_input" { + return Ok(json!({"ok":false,"status":"conflict","id":id})); + } + let allowed = crate::choice::parse_choice(&json!({ + "options": meta["options"], "reply": reply + }))?; + let normalized = if allowed["ok"] == true { + allowed["value"].clone() + } else if meta["freeform"] == true && !reply.trim().is_empty() { + json!(reply.trim()) + } else { + return Ok(json!({"ok":false,"status":"invalid","id":id, + "error":{"code":"input.invalid_choice"}})); + }; + let saved = resume::resume_save(&json!({ + "id": id, "resume_dir": args.get("resume_dir"), + "checkpoint_v2": true, + "status": "resumed", + "task": existing["task"], + "meta": meta, + "result": normalized + }))?; + if saved["ok"] != true { + return Err("unable to commit resumed input".into()); + } + Ok(json!({"ok":true,"status":"resumed","id":id, + "value":normalized,"reused":false})) +} + +#[cfg(test)] +mod tests { + use super::*; + use std::sync::atomic::{AtomicU64, Ordering}; + static SEQ: AtomicU64 = AtomicU64::new(0); + + fn fixture() -> (String, String) { + let id = format!("gate_{}_{}",std::process::id(),SEQ.fetch_add(1,Ordering::Relaxed)); + let dir = format!("target/mq-gate-test-{id}"); + (id, dir) + } + + #[test] + fn persists_answer_without_duplicate_side_effect_or_changed_reply() { + let (id, dir) = fixture(); + let initial = json!({"id":id,"resume_dir":dir,"question":"Choose?", + "options":["chat","office"],"source_revision":"v1", + "session_id":"s1","principal_ref":"u1","freeform":false}); + assert_eq!(input_open(&initial).unwrap()["status"], "waiting_input"); + assert_eq!(input_open(&initial).unwrap()["reused"], true); + let v = json!({"id":id,"resume_dir":dir,"reply":"2", + "source_revision":"v1","session_id":"s1","principal_ref":"u1"}); + assert_eq!(input_resume(&v).unwrap()["value"], "office"); + assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir, + "reply":"office","source_revision":"v1","session_id":"s1", + "principal_ref":"u1"})).unwrap()["reused"], true); + assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir, + "reply":"chat","source_revision":"v1","session_id":"s1", + "principal_ref":"u1"})).unwrap()["status"], "conflict"); + assert_eq!(input_open(&initial).unwrap()["status"], "resumed"); + } + + #[test] + fn prevents_changed_source_or_unauthorized_session() { + let (id, dir) = fixture(); + let initial = json!({"id":id,"resume_dir":dir,"question":"Proceed?", + "options":["yes","no"],"source_revision":"v1", + "session_id":"s1","principal_ref":"u1"}); + input_open(&initial).unwrap(); + for (rev,session) in [("v2","s1"),("v1","other")] { + assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir,"reply":"yes", + "source_revision":rev,"session_id":session, + "principal_ref":"u1"})).unwrap()["status"], "conflict"); + } + } + + #[test] + fn invalid_choice_keeps_gate_open_and_no_freeform_is_enforced() { + let (id, dir) = fixture(); + input_open(&json!({"id":id,"resume_dir":dir,"question":"Pick", + "options":["a","b"],"freeform":false, + "source_revision":"v1"})).unwrap(); + assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir,"reply":"??", + "source_revision":"v1"})).unwrap()["status"], "invalid"); + assert_eq!(resume::resume_load(&json!({"id":id,"resume_dir":dir})).unwrap()["status"], "waiting_input"); + } +} From e8d6dc92fc9c307a9709284355cf0dd5f5bfb442 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:37:44 +0800 Subject: [PATCH 20/66] feat(agent): register user-input pause/reply gate primitives --- plugins/agent/src/lib.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index b40587e..4adf061 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -7,6 +7,7 @@ mod corpus; mod effects; mod eng; mod error; +mod input; mod kb; mod mcp_client; mod mcp_server; @@ -838,6 +839,8 @@ kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear"); kb_ffi!(agent_resume_list, resume::resume_list, "agent_resume_list"); kb_ffi!(agent_choice_parse, choice::parse_choice, "agent_choice_parse"); kb_ffi!(agent_context_scope, context_scope::project, "agent_context_scope"); +kb_ffi!(agent_input_open, input::input_open, "agent_input_open"); +kb_ffi!(agent_input_resume, input::input_resume, "agent_input_resume"); kb_ffi!(agent_error_make, error::make_error, "agent_error_make"); kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry"); kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register"); @@ -969,6 +972,8 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_resume_list", "resume_dir", agent_resume_list), ("agent_choice_parse", "reply,options", agent_choice_parse), ("agent_context_scope", "source,scope,class,function", agent_context_scope), + ("agent_input_open", "id,question,options,source_revision", agent_input_open), + ("agent_input_resume", "id,reply,source_revision", agent_input_resume), ("agent_error_make", "code,message,category", agent_error_make), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_tools_register", "spec,specs", agent_tools_register), From 5795236d1f0ea945b2860d32d1eb5ec0f413a34a Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:37:56 +0800 Subject: [PATCH 21/66] feat(ai): expose durable step-boundary input/reply in flow SKILL --- ext/ai/flow.mq.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index 3741f8c..463c63b 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -87,3 +87,61 @@ Reuse the built-in subtask scheduler. Each child document returns via its `# main`, and successful siblings remain visible if another child fails. Return *[Run bounded Marqdo document tasks](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))*. + + +## input + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Stable step ID | +| question | text | required | User-visible question | +| options | list | required | User-visible choices | +| source_revision | text | required | Pinned Marqdo source revision | +| session_id | text | None | Host-attested session | +| principal_ref | text | None | Host-attested user scope | +| freeform | bool | True | Allow custom user reply | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | waiting_input or previously committed reply | + +Use `id`, `question`, `options`, `source_revision`, `session_id`=None, `principal_ref`=None, `freeform`=True as the inputs for this operation. + +This does not park an interpreter stack. The caller persists a step-boundary +checkpoint, displays the question, and on a new turn uses reply to continue. +The host, not the LLM, must attest session and principal IDs. + +We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load native agent plugin](plugin.load(path=`p`))**. +2. * + Return *[No native gate available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +Return *[Persist one waiting input gate](agent_input_open(id=`id`, question=`question`, options=`options`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, freeform=`freeform`))*. + +## reply + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Existing waiting step | +| reply | text | required | New user response | +| source_revision | text | required | Current pinned source revision | +| session_id | text | None | Host-attested session | +| principal_ref | text | None | Host-attested user scope | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Resolved answer, invalid reply or explicit conflict | + +Use `id`, `reply`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +Matching repeated replies are idempotent. A conflicting reply, changed document +or changed session fails without executing any SKILL or side effect. + +We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load native agent plugin](plugin.load(path=`p`))**. +2. * + Return *[No native gate available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +Return *[Commit the verified user reply](agent_input_resume(id=`id`, reply=`reply`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. From d5ab9daebba9df6d234289de381d670e72d6c451 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:38:26 +0800 Subject: [PATCH 22/66] feat(agent): classify parallel child successes, failures and unknown outcomes --- plugins/agent/src/parallel.rs | 81 +++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 plugins/agent/src/parallel.rs diff --git a/plugins/agent/src/parallel.rs b/plugins/agent/src/parallel.rs new file mode 100644 index 0000000..e5d6ad2 --- /dev/null +++ b/plugins/agent/src/parallel.rs @@ -0,0 +1,81 @@ +//! Deterministic fan-out results: never discard a successful sibling and never +//! infer success from a completed wait protocol alone. + +use serde_json::{json, Value}; + +pub fn report(args: &Value) -> Result { + let results = args + .get("results") + .and_then(Value::as_array) + .ok_or_else(|| "results must be ordered subtask result list".to_string())?; + if results.len() > 10_000 { + return Err("parallel result count exceeds scheduler limit".into()); + } + let mut passed = 0usize; + let mut failed = 0usize; + let mut unknown = 0usize; + let mut entries = Vec::with_capacity(results.len()); + for (index, child) in results.iter().enumerate() { + let transport = child.get("ok").and_then(Value::as_bool); + let body = child.get("value").unwrap_or(&Value::Null); + let status = match (transport, body.get("code").and_then(Value::as_i64)) { + (Some(true), Some(0)) => { passed += 1; "succeeded" } + (Some(true), Some(_)) | (Some(false), _) => { failed += 1; "failed" } + _ => { unknown += 1; "uncertain" } + }; + // Raw child result is kept as data; the model sees only an optional + // bounded summary. The host may store detailed output as an artifact. + let detail = child.get("error") + .and_then(Value::as_str) + .or_else(|| body.get("stderr").and_then(Value::as_str)) + .unwrap_or(""); + let brief: String = detail.chars().take(280).collect(); + entries.push(json!({ + "index": index, + "status": status, + "summary": brief, + "result": child + })); + } + let status = if unknown != 0 { + "uncertain" + } else if failed == 0 { + "succeeded" + } else if passed > 0 { + "partial" + } else { + "failed" + }; + Ok(json!({ + "ok": failed == 0 && unknown == 0, + "schema": "AgentParallelResultV1", + "status": status, + "succeeded": passed, + "failed": failed, + "uncertain": unknown, + "items": entries + })) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn preserves_success_and_exposes_failed_child() { + let result = report(&json!({"results":[ + {"ok":true,"value":{"code":0,"value":"good"}}, + {"ok":true,"value":{"code":2,"stderr":"failed"}}, + {"ok":false,"error":"timeout"} + ]})).unwrap(); + assert_eq!(result["status"], "partial"); + assert_eq!(result["succeeded"], 1); + assert_eq!(result["failed"], 2); + assert_eq!(result["items"][0]["status"], "succeeded"); + } + #[test] + fn unknown_child_cannot_be_mislabeled_successful() { + let value = report(&json!({"results":[{"ok":true,"value":{"value":"no code"}}]})).unwrap(); + assert_eq!(value["status"], "uncertain"); + assert_eq!(value["ok"], false); + } +} From c7c0f66d1f94580543c70836cec30e2830372e71 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:38:33 +0800 Subject: [PATCH 23/66] feat(agent): register typed concurrent task result aggregator --- plugins/agent/src/lib.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 4adf061..9c210c8 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -13,6 +13,7 @@ mod mcp_client; mod mcp_server; mod memory; mod output; +mod parallel; mod resume; mod route; mod sandbox; @@ -841,6 +842,7 @@ kb_ffi!(agent_choice_parse, choice::parse_choice, "agent_choice_parse"); kb_ffi!(agent_context_scope, context_scope::project, "agent_context_scope"); kb_ffi!(agent_input_open, input::input_open, "agent_input_open"); kb_ffi!(agent_input_resume, input::input_resume, "agent_input_resume"); +kb_ffi!(agent_parallel_report, parallel::report, "agent_parallel_report"); kb_ffi!(agent_error_make, error::make_error, "agent_error_make"); kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry"); kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register"); @@ -974,6 +976,7 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_context_scope", "source,scope,class,function", agent_context_scope), ("agent_input_open", "id,question,options,source_revision", agent_input_open), ("agent_input_resume", "id,reply,source_revision", agent_input_resume), + ("agent_parallel_report", "results", agent_parallel_report), ("agent_error_make", "code,message,category", agent_error_make), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_tools_register", "spec,specs", agent_tools_register), From b2f97e72c3678e8fa9ebca444389777b97b1a4dc Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:38:58 +0800 Subject: [PATCH 24/66] build(agent): lock pulldown-cmark dependency for native scoped context --- Cargo.lock | 1 + 1 file changed, 1 insertion(+) diff --git a/Cargo.lock b/Cargo.lock index cc963b5..8c8fce1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -668,6 +668,7 @@ version = "0.1.0" dependencies = [ "chrono", "marqdo-plugin-sdk", + "pulldown-cmark", "serde_json", ] From e48fd5b0f4b8dc1e4411b2d409d9034087c02390 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:39:06 +0800 Subject: [PATCH 25/66] feat(ai): aggregate concurrent child status without losing successful siblings --- ext/ai/flow.mq.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index 463c63b..26c1c1b 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -79,14 +79,20 @@ We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. | 返回 | 类型 | 说明 | |---|---|---| -| result | list | Ordered child outcomes, including failures | +| result | map | Succeeded, partial, failed or uncertain child outcomes | Use `tasks`, `limit`=2, `timeout_ms`=30000 as the inputs for this operation. Reuse the built-in subtask scheduler. Each child document returns via its `# main`, and successful siblings remain visible if another child fails. -Return *[Run bounded Marqdo document tasks](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))*. +We retain **results = [Run bounded Marqdo document tasks](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))**. +We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load native agent plugin](plugin.load(path=`p`))**. + Return *[Preserve success, failure and uncertain child outcomes](agent_parallel_report(results=`results`))*. +2. * + Return *[Native result classifier unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. ## input From cf73fcf1efc33ab534fa9ac3ba9ee0683339f0d0 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:39:37 +0800 Subject: [PATCH 26/66] feat(ai): add allowlisted SKILL enter via standard Marqdo subtasks --- ext/ai/flow.mq.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index 26c1c1b..cc7d786 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -151,3 +151,28 @@ We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))** Return *[No native gate available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. Return *[Commit the verified user reply](agent_input_resume(id=`id`, reply=`reply`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + + +## enter + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| skill | text | required | Model-selected registered name | +| registry | map | required | Trusted name → path mapping | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Subtask result, or blocked unknown skill | + +Use `skill`, `registry` as the inputs for this operation. + +Never execute a raw model-generated path. Resolve a registered skill name to +an author-controlled document, then call its `# main` through the normal Marqdo +subtask and effect permissions. The caller must provide a trusted registry. + +We retain **path = [Resolve registered SKILL](json.get(value=`registry`, key=`skill`))**. +1. not `path` + Return *[Unknown skill is blocked](json.parse(text="{\"ok\":false,\"status\":\"unsupported_skill\"}"))*. +2. * + We retain **task = [Spawn registered Marqdo document](subtask.spawn(path=`path`))**. + Return *[Await the subtask result](subtask.wait(id=`task`))*. From 633436e40fbbd94ee574532ff08eef4b5cfa4377 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:39:53 +0800 Subject: [PATCH 27/66] fix(agent): compare owned JSON values with dereferenced optional identity values --- plugins/agent/src/input.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/agent/src/input.rs b/plugins/agent/src/input.rs index 8100f23..f01a935 100644 --- a/plugins/agent/src/input.rs +++ b/plugins/agent/src/input.rs @@ -95,8 +95,8 @@ pub fn input_open(args: &Value) -> Result { let same = meta["question"] == query && meta["options"] == labels && meta["source_revision"] == version - && meta["session_id"] == args.get("session_id").unwrap_or(&Value::Null) - && meta["principal_ref"] == args.get("principal_ref").unwrap_or(&Value::Null); + && meta["session_id"] == *args.get("session_id").unwrap_or(&Value::Null) + && meta["principal_ref"] == *args.get("principal_ref").unwrap_or(&Value::Null); if same && existing["ok"] == true { let status = existing["status"].as_str().unwrap_or("unknown"); return Ok(json!({ From 9031c106a147d9ca188453db734331dbc4466e6c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:40:08 +0800 Subject: [PATCH 28/66] test(ai): add offline Marqdo interpreter smoke for native choice and scoped context --- tests/ext/ai-native-flow.mq.md | 46 ++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 tests/ext/ai-native-flow.mq.md diff --git a/tests/ext/ai-native-flow.mq.md b/tests/ext/ai-native-flow.mq.md new file mode 100644 index 0000000..194e205 --- /dev/null +++ b/tests/ext/ai-native-flow.mq.md @@ -0,0 +1,46 @@ +--- +markup: occlusion +title: AI native flow offline smoke +import: + flow: ext/ai/flow.mq.md + context: ext/ai/context.mq.md + json: lib/json.mq.md + sys: lib/sys.mq.md +--- + +# main + +This fixture tests the real Marqdo interface without a model provider. +It refuses an invalid choice and retrieves only the designated function +rather than guessing another SKILL or importing the full document. + +**opts = > json.parse text=["chat","office"]** +**pick = > flow.parse_choice reply="选择:office" options=`opts`** +**value = > json.get value=`pick` key="value"** +1. `value` == "office" + **_ = 1** +2. * + > sys.exit code=11 + +**invalid = > flow.parse_choice reply="chat 或 office" options=`opts`** +**not_ok = > json.get value=`invalid` key="ok"** +1. `not_ok` + > sys.exit code=12 +2. * + **_ = 1** + +**ctx = > context.scope scope="function" class="main" function="probe" max_chars=200** +**ok = > json.get value=`ctx` key="ok"** +1. `ok` + **_ = 1** +2. * + > sys.exit code=13 + +Return *"ai-flow-native-ok"*. + +## probe + +This private helper's narrative should be extracted by the scoped selector +without including the root SKILL or neighboring function definitions. + +Return *"probe"*. From 88490e3092d7a97b7e4cab86bdb4de4fd2fcac7c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:40:15 +0800 Subject: [PATCH 29/66] ci(ai): execute real native choice and scoped-context Marqdo smoke --- .github/workflows/executable-knowledge.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml index 6d3882d..eec00f9 100644 --- a/.github/workflows/executable-knowledge.yml +++ b/.github/workflows/executable-knowledge.yml @@ -22,6 +22,9 @@ jobs: cargo run --locked -- check ext/ai/flow.mq.md cargo run --locked -- check ext/ai/recovery.mq.md cargo run --locked -- check ext/ai/context.mq.md + cargo run --locked -- check tests/ext/ai-native-flow.mq.md + - name: Native AI flow interpreter smoke (offline) + run: cargo run --locked -- run tests/ext/ai-native-flow.mq.md - name: Workbench contracts (M00–M06 / F-subset) run: cargo test --test workbench_contracts --locked - name: Offline executable-knowledge gate From 02a4f2d20dde223edacbcd9d374869ccdaed9936 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:40:50 +0800 Subject: [PATCH 30/66] fix(agent): skip YAML setext lookalikes in document-scope parser --- plugins/agent/src/context_scope.rs | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/plugins/agent/src/context_scope.rs b/plugins/agent/src/context_scope.rs index bb9a148..b970d57 100644 --- a/plugins/agent/src/context_scope.rs +++ b/plugins/agent/src/context_scope.rs @@ -97,7 +97,13 @@ pub fn project(args: &Value) -> Result { .and_then(Value::as_u64) .unwrap_or(1600) .clamp(32, 16000) as usize; - let marks = headings(&source); + // YAML frontmatter may look like a setext Markdown heading; never treat it + // as a Marqdo class or function boundary. + let front_end = frontmatter_end(&source); + let marks: Vec
= headings(&source) + .into_iter() + .filter(|heading| heading.start >= front_end) + .collect(); let results: Vec<(usize, usize)> = match scope { "file" => { let end = marks.first().map_or(source.len(), |h| h.start); From 60a3b84a84de9c005d47b23e88ab505bb70607f9 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:41:08 +0800 Subject: [PATCH 31/66] test(ai): exercise durable input and reply from a real Marqdo program --- tests/ext/ai-native-flow.mq.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tests/ext/ai-native-flow.mq.md b/tests/ext/ai-native-flow.mq.md index 194e205..85a699d 100644 --- a/tests/ext/ai-native-flow.mq.md +++ b/tests/ext/ai-native-flow.mq.md @@ -36,6 +36,14 @@ rather than guessing another SKILL or importing the full document. 2. * > sys.exit code=13 +**gate = > flow.input id="ai_native_flow_ci_gate" question="Continue?" options=`opts` source_revision="fixture-v1" freeform=False** +**answered = > flow.reply id="ai_native_flow_ci_gate" reply="office" source_revision="fixture-v1"** +**answer = > json.get value=`answered` key="value"** +1. `answer` == "office" + **_ = 1** +2. * + > sys.exit code=14 + Return *"ai-flow-native-ok"*. ## probe From c64ec99115f33b87e3f363dcde9cbc35ab3cf37f Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:41:28 +0800 Subject: [PATCH 32/66] feat(ai): expose minimal ask/start/wait on top of native LLM and subtask APIs --- ext/ai/flow.mq.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index cc7d786..b431cb4 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -176,3 +176,60 @@ We retain **path = [Resolve registered SKILL](json.get(value=`registry`, key=`sk 2. * We retain **task = [Spawn registered Marqdo document](subtask.spawn(path=`path`))**. Return *[Await the subtask result](subtask.wait(id=`task`))*. + + +## ask + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| prompt | text | required | Short local prompt | +| model | any | None | Configured model selection | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | text | Model reply (not yet a verified tool call) | + +Use `prompt`, `model`=None as the inputs for this operation. + +Ask only what the current function needs. The reply remains data until an +explicit verifier accepts it. The LLM adapter owns provider configuration. + +Return *[Ask the configured model](llm.ask(prompt=`prompt`, model=`model`))*. + +## start + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| path | text | required | Trusted registered Marqdo document | +| args | list | None | Optional child CLI arguments | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | number | Child task handle | + +Use `path`, `args`=None as the inputs for this operation. + +Start an isolated SKILL document asynchronously, after the calling host has +validated its path and required process.exec permission. No model-generated +raw path is a valid grant. + +Return *[Start one Marqdo document](subtask.spawn(path=`path`, args=`args`))*. + +## wait + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | number | required | Child task handle | +| timeout_ms | number | 30000 | Maximum wait time | +| cancel | bool | False | Cancel on timeout | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Child result, timeout or cancellation | + +Use `id`, `timeout_ms`=30000, `cancel`=False as the inputs for this operation. + +A successful wait protocol is not proof of a successful child execution: +inspect the child exit code before using its result. + +Return *[Wait for the child](subtask.wait_timeout(id=`id`, timeout_ms=`timeout_ms`, cancel=`cancel`))*. From add6a7d32ca84eb369ebc13d6965ea1223057871 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:42:07 +0800 Subject: [PATCH 33/66] docs(agent): record implemented contracts and precise VM/runtime completion gates --- doc/design/native-agent-flow-v3.md | 91 ++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 doc/design/native-agent-flow-v3.md diff --git a/doc/design/native-agent-flow-v3.md b/doc/design/native-agent-flow-v3.md new file mode 100644 index 0000000..d4b37c3 --- /dev/null +++ b/doc/design/native-agent-flow-v3.md @@ -0,0 +1,91 @@ +# Marqdo native agent flow — implementation contract + +Status: **incremental, draft**. This document distinguishes implemented interfaces from +the required interpreter/runtime changes. Do not claim stack-level suspension or +exactly-once external writes based on a checkpoint file. + +## Author surface (implemented in this branch) + +| Module | Function | Contract | +|---|---|---| +| ext/ai/context.mq.md | scope | Select a bounded source excerpt using parsed Markdown headings; ambiguous names fail closed | +| ext/ai/context.mq.md | pack | Compact caller-provided file/class/function text via ContextPackV2 | +| ext/ai/flow.mq.md | ask/choose/parse_choice | One short decision, allowed-choice verification, at most one format repair | +| ext/ai/flow.mq.md | input/reply | Durable step-boundary user-input gate keyed by id + source revision and scope | +| ext/ai/flow.mq.md | start/wait/parallel | Existing Marqdo subtask scheduler, failure-preserving parallel result aggregation | +| ext/ai/flow.mq.md | enter | Resolve only author-supplied registered skill name, run via standard subtask path | +| ext/ai/recovery.mq.md | decide/save/load | Native error policy and CheckpointV2; no implicit unsafe re-execution | + +The native agent plugin provides `agent_choice_parse`, `agent_context_scope`, +`agent_input_open`, `agent_input_resume` and `agent_parallel_report`. +Plugin errors must be visible, never converted into a fabricated successful answer. + +## Invariants + +- A model choice is untrusted data until verified against an explicit option list. +- An imported module is **not** automatically part of a model prompt. +- The requested heading scope, not the entire source file, is the prompt source. +- A pending user-input gate owns a persistent checkpoint, not a blocked interpreter thread. +- The same answer may be returned repeatedly; a competing answer or stale revision conflicts. +- A completed subtask wait is distinct from a successful child exit. +- Existing successful siblings remain visible when one subtask fails. +- Writes, executable effects and external writes remain under ToolSpec permissions, + the EffectLedger and source-version checks. +- No component may silently broaden a tool's authorization on failure. + +## Important limitations in this branch + +The input/reply gate stores an explicit **step boundary**. It does not yet persist +an arbitrary bytecode interpreter frame. Applications must choose and re-enter +their next Marqdo function explicitly after receiving a verified input answer. +The current source selector relies on a Markdown parser plus Marqdo heading +conventions, not on the compiler's resolved module/class/function AST and symbols. +Host identity inputs are supplied by the caller; production applications must +attest them from their authenticated session, never use model-generated identity. +The parallel wrapper reuses `subtask.run_many` and does not add durable child +lease orchestration. Live provider tests and real 1B-model benchmarking remain open. + +## Required VM/runtime completion: suspended execution + +1. Introduce `WaitingInput` as a scheduler state, distinct from terminal failure. + Save the logical run, program counter at a safe suspension boundary, bound + inputs, variable snapshot, module and tool digests, and effect watermark. +2. Resume via a new attempt linked to the original logical run, but never + automatically repeat committed effects. Preserve cancellation and budget. +3. The resume endpoint must be atomic (revision CAS), authenticate principal + and workspace, verify source and tool schema revisions, and deduplicate + repeated reply requests. Do not trust IDs inside model text. +4. Handle interrupted worker, partial snapshot, stale input, invalid choice and + unknown external write as separate outcomes. Treat unknown writes as + reconciliation-required; do not invent exactly-once guarantees. +5. Persist only serializable language values at declared safe points. If a + foreign kernel, socket or native handle is live, explicitly refuse + transparent frame recovery and preserve a safe step-level restart option. + +## Required durable parallel execution + +A parent dispatches child `.mq.md` functions using registered paths, grants +minimal capabilities, shares budget and rate limits, and persists a child task +manifest. Child completion records a status, value ref, output digest and ledger +watermark before the parent merges results. For same-resource writes, use +serialized revisions and explicit commit order. On parent cancellation, stop +new children and request child cancellation; do not assume remote writes rolled +back. On recovery, reconcile child attempts and reuse successful results. + +## Release gates + +| Test | Required observation | +|---|---| +| compiler/import check | All new `.mq.md` functions pass contract checks and execute via ABI | +| small model outputs | Exact, labeled, fenced and numeric options normalize; mixed options fail | +| input gate crash | After checkpoint, reply is committed once; alternate reply conflicts | +| source drift | Original gate cannot resume against changed source revision | +| context isolation | Class/function selectors reject ambiguity and ignore fenced headings | +| concurrent partial | Failed/uncertain child never discards successful siblings | +| unknown write | Neither retry nor recovered child duplicates an unconfirmed effect | +| long-run cancellation | Worker/child task termination preserves usable artifacts and receipts | +| compatibility | Existing `agent.step/plan/run` and workbooks remain callable | +| model evaluation | Tokens/decision, semantic validity, end-to-end completion, recovery overhead | + +Do not merge the branch as a completed runtime refactor until the relevant +runtime gates, including crash injection and multi-worker concurrency, pass. From edbf241d99e863752fac64d11dc19678b290490c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:43:24 +0800 Subject: [PATCH 34/66] feat(ai): compose current user and scoped file/class/function source into a bounded context pack --- ext/ai/context.mq.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/ext/ai/context.mq.md b/ext/ai/context.mq.md index 3905067..375ba07 100644 --- a/ext/ai/context.mq.md +++ b/ext/ai/context.mq.md @@ -72,3 +72,42 @@ We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))** Return *[No native parser available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\",\"text\":null}"))*. Return *[Project the requested document scope](agent_context_scope(source=`source`, scope=`scope`, class=`class`, function=`function`, max_chars=`max_chars`))*. + + +## compose + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| user | text | required | Latest user input | +| class | text | required | Current class name | +| function | text | required | Current function name | +| source | text | None | Override current entry source | +| budget_tokens | number | 2048 | Small-model context budget | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | ContextPackV2 or an explicit failed selector | + +Use `user`, `class`, `function`, `source`=None, `budget_tokens`=2048 as the inputs for this operation. + +Project file, class and function scopes independently. Refuse ambiguous names +rather than silently importing an unrelated class or the entire source. The +latest user input stays in the retained portion of the resulting context pack. + +We retain **f = [Select file preface](scope(scope="file", source=`source`, max_chars=500))**. +We retain **c = [Select current class](scope(scope="class", class=`class`, source=`source`, max_chars=800))**. +We retain **n = [Select current function](scope(scope="function", class=`class`, function=`function`, source=`source`, max_chars=1500))**. +We retain **f_ok = [Check file selection](json.get(value=`f`, key="ok"))**. +We retain **c_ok = [Check class selection](json.get(value=`c`, key="ok"))**. +We retain **n_ok = [Check function selection](json.get(value=`n`, key="ok"))**. +1. not `f_ok` + Return *f*. +2. not `c_ok` + Return *c*. +3. not `n_ok` + Return *n*. +4. * + We retain **ft = [Read file preface](json.get(value=`f`, key="text"))**. + We retain **ct = [Read class explanation](json.get(value=`c`, key="text"))**. + We retain **nt = [Read function explanation](json.get(value=`n`, key="text"))**. + Return *[Compact only the selected scopes](pack(user=`user`, file=`ft`, class=`ct`, function=`nt`, budget_tokens=`budget_tokens`))*. From ee677478be37fe30fc3e238d1b929183ae3bc2bf Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:43:30 +0800 Subject: [PATCH 35/66] test(ai): verify file/class/function context composition in Marqdo interpreter --- tests/ext/ai-native-flow.mq.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/tests/ext/ai-native-flow.mq.md b/tests/ext/ai-native-flow.mq.md index 85a699d..cce2a01 100644 --- a/tests/ext/ai-native-flow.mq.md +++ b/tests/ext/ai-native-flow.mq.md @@ -36,6 +36,13 @@ rather than guessing another SKILL or importing the full document. 2. * > sys.exit code=13 +**packed = > context.compose user="Test the route" class="main" function="probe" budget_tokens=2048** +**pack_schema = > json.get value=`packed` key="schema"** +1. `pack_schema` == "ContextPackV2" + **_ = 1** +2. * + > sys.exit code=15 + **gate = > flow.input id="ai_native_flow_ci_gate" question="Continue?" options=`opts` source_revision="fixture-v1" freeform=False** **answered = > flow.reply id="ai_native_flow_ci_gate" reply="office" source_revision="fixture-v1"** **answer = > json.get value=`answered` key="value"** From 629ad8ed39177951569514a88e84379c9de377f3 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:43:59 +0800 Subject: [PATCH 36/66] feat(agent): tolerate short deterministic small-model selection phrases --- plugins/agent/src/choice.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/plugins/agent/src/choice.rs b/plugins/agent/src/choice.rs index 5a4e300..b3b8db7 100644 --- a/plugins/agent/src/choice.rs +++ b/plugins/agent/src/choice.rs @@ -45,6 +45,12 @@ fn strip_label(s: &str) -> &str { fn single_choice(options: &[String], reply: &str) -> Option { let raw = strip_label(strip_fence(reply)); + // Small models often prepend a short selection verb. Accept only the + // verb followed by a complete allowed value; explanations stay invalid. + let raw = raw.trim(); + let raw = ["我选择", "我选", "I choose ", "I pick ", "选中"].iter() + .find_map(|p| raw.strip_prefix(p).map(str::trim)) + .unwrap_or(raw); let value = canonical(raw); // Never infer a routing decision from arbitrary prose. let matches: Vec<&String> = options @@ -122,6 +128,8 @@ mod tests { assert_eq!(check("选择:office")["value"], "office"); assert_eq!(check("```text\nchat\n```")["value"], "chat"); assert_eq!(check("2")["value"], "office"); + assert_eq!(check("我选择 chat")["value"], "chat"); + assert_eq!(check("I choose office")["value"], "office"); } #[test] From 2dfa0b2a5becb347f67efac08aeac899c4e4ba8f Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:46:24 +0800 Subject: [PATCH 37/66] fix(ai): do not mistake LLM transport errors for choices or trigger format repair --- ext/ai/flow.mq.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index b431cb4..346fd69 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -57,15 +57,26 @@ format correction; never silently select the nearest-looking option. We retain **opts = [Encode allowed values](json.stringify(value=`options`))**. We retain **prompt = "Choose exactly one of these options. Return its name only, no explanation:\n" + opts + "\nInput:\n" + input**. -We retain **reply = [Ask the model once](llm.ask(prompt=`prompt`, model=`model`))**. -We retain **parsed = [Validate the model reply](parse_choice(reply=`reply`, options=`options`))**. +We retain **m = [Build one model handle](llm.create(model=`model`))**. +We retain **turn = [Ask the model once](m.ask(prompt=`prompt`))**. +We retain **err = [Check model transport error](json.get(value=`turn`, key="error"))**. +1. `err` + Return *turn*. +2. * + We retain **reply = [Read model answer](json.get(value=`turn`, key="text"))**. + We retain **parsed = [Validate the model reply](parse_choice(reply=`reply`, options=`options`))**. We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. 1. `ok` Return *parsed*. 2. `repair` We retain **fix = "Your answer was not an exact allowed option. Return only ONE option name from:\n" + opts**. - We retain **again = [Retry the format only once](llm.ask(prompt=`fix`, model=`model`))**. - Return *[Validate the repaired reply](parse_choice(reply=`again`, options=`options`))*. + We retain **fixed = [Retry the format only once](m.ask(prompt=`fix`))**. + We retain **repair_error = [Read transport error](json.get(value=`fixed`, key="error"))**. + 1. `repair_error` + Return *fixed*. + 2. * + We retain **again = [Read corrected answer](json.get(value=`fixed`, key="text"))**. + Return *[Validate the repaired reply](parse_choice(reply=`again`, options=`options`))*. 3. * Return *parsed*. From 06e61efc51d62e2bcd3c8c6ee6fa950b358b9a0d Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:51:51 +0800 Subject: [PATCH 38/66] feat(agent): implement plugin-only durable step workflow with deterministic next/commit/cancel and tests --- plugins/agent/src/workflow.rs | 346 ++++++++++++++++++++++++++++++++++ 1 file changed, 346 insertions(+) create mode 100644 plugins/agent/src/workflow.rs diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs new file mode 100644 index 0000000..d96b174 --- /dev/null +++ b/plugins/agent/src/workflow.rs @@ -0,0 +1,346 @@ +//! Plugin-only durable step workflow. +//! No interpreter-frame serialization: every model/tool decision is a checkpointed +//! transition. This state machine issues actions but never executes arbitrary code. + +use std::fs::{self, OpenOptions}; +use std::path::PathBuf; +use serde_json::{json, Value}; + +use crate::{choice, parallel, resume}; + +const MAX_STEPS: usize = 128; + +struct Guard(PathBuf); +impl Drop for Guard { + fn drop(&mut self) { let _ = fs::remove_file(&self.0); } +} + +fn field<'a>(v: &'a Value, key: &str) -> Result<&'a str, String> { + v.get(key).and_then(Value::as_str).filter(|x| !x.is_empty()) + .ok_or_else(|| format!("workflow requires text {key}")) +} + +fn safe_key(s: &str) -> bool { + !s.is_empty() && s.len() <= 100 + && s.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_') +} + +fn storage(args: &Value) -> Result { + let rel = args.get("resume_dir").and_then(Value::as_str) + .unwrap_or(".marqdo/agent-resume"); + let path = PathBuf::from(rel); + if path.is_absolute() || path.components().any(|part| + matches!(part, std::path::Component::ParentDir | std::path::Component::Prefix(_))) + { + return Err("resume_dir must be relative with no parent traversal".into()); + } + let base = crate::host_query_json("cwd").ok() + .and_then(|v| v.as_str().map(PathBuf::from)) + .unwrap_or(std::env::current_dir().map_err(|e| e.to_string())?); + let dir = base.join(path); + fs::create_dir_all(&dir).map_err(|e| format!("workflow mkdir: {e}"))?; + Ok(dir) +} + +fn lock(args: &Value, id: &str) -> Result { + if !safe_key(id) { + return Err("workflow id must be <=100 ASCII letters, numbers, - or _".into()); + } + let path = storage(args)?.join(format!("{id}.flow-lock")); + OpenOptions::new().write(true).create_new(true).open(&path) + .map_err(|e| format!("workflow busy or stale lock; review before recovering: {e}"))?; + Ok(Guard(path)) +} + +fn checkpoint_args(args: &Value, id: &str) -> Value { + json!({"id": id, "resume_dir": args.get("resume_dir")}) +} + +fn read(args: &Value, id: &str) -> Result { + resume::resume_load(&checkpoint_args(args,id)) +} + +fn context(args: &Value) -> Value { + json!({ + "source_revision": args.get("source_revision").cloned().unwrap_or(Value::Null), + "session_id": args.get("session_id").cloned().unwrap_or(Value::Null), + "principal_ref": args.get("principal_ref").cloned().unwrap_or(Value::Null) + }) +} + +fn check_context(args: &Value, ckpt: &Value) -> bool { + ckpt["meta"]["identity"] == context(args) +} + +fn validate_steps(args: &Value) -> Result { + let steps = args.get("steps").and_then(Value::as_array) + .ok_or_else(|| "steps must be a list".to_string())?; + if steps.is_empty() || steps.len() > MAX_STEPS { + return Err("steps must contain 1..=128 items".into()); + } + let mut seen = std::collections::HashSet::new(); + for s in steps { + let id = field(s, "id")?; + if !safe_key(id) || !seen.insert(id) { + return Err("step ids must be unique safe identifiers".into()); + } + let kind = field(s, "kind")?; + if !matches!(kind, "model" | "input" | "skill" | "parallel" | "return") { + return Err(format!("unsupported step kind: {kind}")); + } + if matches!(kind, "model" | "input") { + let options = s.get("options").and_then(Value::as_array) + .ok_or_else(|| "choice step requires options list".to_string())?; + let _ = choice::parse_choice(&json!({"reply":"","options":options}))?; + if kind == "input" { let _ = field(s, "question")?; } + } + if kind == "skill" { let _ = field(s, "skill")?; } + if kind == "parallel" && !s.get("tasks").is_some_and(Value::is_array) { + return Err("parallel step requires tasks array".into()); + } + } + Ok(Value::Array(steps.clone())) +} + +fn state(ckpt: &Value) -> Result<(&Value,usize),String> { + let meta = ckpt.get("meta").ok_or("missing workflow metadata")?; + if meta.get("kind").and_then(Value::as_str) != Some("MarqdoAgentFlowV1") { + return Err("checkpoint is not a workflow".into()); + } + let index = meta.get("cursor").and_then(Value::as_u64) + .ok_or("missing workflow cursor")? as usize; + Ok((meta,index)) +} + +fn save(args: &Value, id: &str, meta: &Value, status: &str) -> Result<(),String> { + let result = resume::resume_save(&json!({ + "id": id, + "resume_dir": args.get("resume_dir"), + "checkpoint_v2": true, + "status": status, + "meta": meta, + "completed_steps": meta["completed"], + "step_id": meta["steps"].get(meta["cursor"].as_u64().unwrap_or(0) as usize) + .and_then(|x| x.get("id")).cloned().unwrap_or(Value::Null) + }))?; + if result["ok"] != true { return Err("workflow checkpoint write failed".into()); } + Ok(()) +} + +/// Register a bounded, frozen plan. Re-opening never resets a progressed plan. +pub fn open(args: &Value) -> Result { + let id = field(args,"id")?; + let _guard = lock(args,id)?; + let revision = field(args,"source_revision")?; + if revision.len()>256 { return Err("source_revision too long".into()); } + let steps = validate_steps(args)?; + let existing = read(args,id)?; + let identity = context(args); + if existing["found"] == true { + if existing["ok"] == true + && existing["meta"]["identity"] == identity + && existing["meta"]["steps"] == steps + { + return next_doc(&existing,id,true); + } + return Ok(json!({"ok":false,"status":"conflict","error":"workflow.id_or_revision_reused"})); + } + let meta = json!({ + "kind":"MarqdoAgentFlowV1", + "identity":identity, + "steps":steps, + "cursor":0, + "completed":[], + }); + save(args,id,&meta,"running")?; + Ok(json!({"ok":true,"id":id,"status":"created","cursor":0})) +} + +fn next_doc(ckpt: &Value, id: &str, reused: bool) -> Result { + let (meta,index)=state(ckpt)?; + let steps = meta["steps"].as_array().ok_or("invalid steps")?; + if index>=steps.len() { + return Ok(json!({"ok":true,"id":id,"status":"succeeded", + "cursor":index,"completed":meta["completed"],"reused":reused})); + } + let step=&steps[index]; + let status=ckpt["status"].as_str().unwrap_or("running"); + if status=="blocked" || status=="uncertain" || status=="cancelled" { + return Ok(json!({"ok":false,"id":id,"status":status, + "cursor":index,"step":step,"completed":meta["completed"]})); + } + let waiting=match step["kind"].as_str().unwrap_or("") { + "model"=>"waiting_model", + "input"=>"waiting_input", + "skill" | "parallel"=>"ready_tool", + "return"=>"ready_return", + _=>"blocked" + }; + Ok(json!({"ok":true,"id":id,"status":waiting, + "cursor":index,"step":step,"completed":meta["completed"],"reused":reused})) +} + +/// Query the durable next action. This is non-blocking and does not invoke LLM. +pub fn next(args: &Value) -> Result { + let id=field(args,"id")?; + let ckpt=read(args,id)?; + if ckpt["ok"]!=true || !check_context(args,&ckpt) { + return Ok(json!({"ok":false,"id":id,"status":"not_found_or_mismatched"})); + } + next_doc(&ckpt,id,false) +} + +/// Commit a verified result for the exact current step. All mutations are +/// serialized with a lock; a completed step cannot be committed a second time. +pub fn commit(args: &Value) -> Result { + let id=field(args,"id")?; + let _guard=lock(args,id)?; + let step_id=field(args,"step_id")?; + let ckpt=read(args,id)?; + if ckpt["ok"]!=true || !check_context(args,&ckpt) { + return Ok(json!({"ok":false,"status":"not_found_or_mismatched"})); + } + let (meta,index)=state(&ckpt)?; + let steps=meta["steps"].as_array().ok_or("invalid steps")?; + let response=args.get("response").ok_or("missing response")?; + if index>=steps.len() { + let previous = meta["completed"].as_array().ok_or("invalid completed")?; + if previous.iter().any(|x|x["step_id"]==step_id && x["value"]==*response) { + return Ok(json!({"ok":true,"status":"succeeded","reused":true})); + } + return Ok(json!({"ok":false,"status":"already_finished"})); + } + let step=&steps[index]; + if step["id"]!=step_id { + if meta["completed"].as_array().is_some_and(|list| + list.iter().any(|x|x["step_id"]==step_id && x["value"]==*response)) + { + return Ok(json!({"ok":true,"status":"already_committed","reused":true})); + } + return Ok(json!({"ok":false,"status":"step_conflict"})); + } + if ckpt["status"]!="running" { + return Ok(json!({"ok":false,"status":"blocked","reason":ckpt["status"]})); + } + let kind=field(step,"kind")?; + let value = match kind { + "model" | "input" => { + let reply = response.as_str().ok_or("model/input response must be text")?; + let valid=choice::parse_choice(&json!({"options":step["options"],"reply":reply}))?; + if valid["ok"]!=true { + return Ok(json!({"ok":false,"status":"invalid_choice", + "error":valid["error"]})); + } + valid["value"].clone() + } + "skill" => { + if response["ok"]!=true { + return Ok(json!({"ok":false,"status":"tool_not_verified", + "reason":"only verified successful tool result may be committed"})); + } + response.clone() + } + "parallel" => { + let report=parallel::report(&json!({"results":response}))?; + if report["ok"]!=true { + return Ok(json!({"ok":false, + "status": if report["uncertain"].as_u64().unwrap_or(0)>0 { + "uncertain" } else {"partial"}, + "report":report, + "reason":"preserve successful children; reconcile or retry failed children separately"})); + } + report + } + "return" => response.clone(), + _ => return Err("invalid step kind".into()), + }; + let mut new_meta=meta.clone(); + new_meta["cursor"]=json!(index+1); + new_meta["completed"].as_array_mut().ok_or("completed not array")? + .push(json!({"step_id":step_id,"value":value})); + let terminal=index+1==steps.len(); + save(args,id,&new_meta,if terminal {"succeeded"} else {"running"})?; + Ok(json!({"ok":true,"id":id, + "status":if terminal {"succeeded"} else {"advanced"}, + "cursor":index+1,"value":value,"reused":false})) +} + +pub fn cancel(args: &Value) -> Result { + let id=field(args,"id")?; + let _guard=lock(args,id)?; + let ckpt=read(args,id)?; + if ckpt["ok"]!=true || !check_context(args,&ckpt) { + return Ok(json!({"ok":false,"status":"not_found_or_mismatched"})); + } + if ckpt["status"]=="succeeded" { + return Ok(json!({"ok":false,"status":"already_finished"})); + } + let (meta,_)=state(&ckpt)?; + save(args,id,meta,"cancelled")?; + Ok(json!({"ok":true,"id":id,"status":"cancelled"})) +} + +#[cfg(test)] +mod tests { + use super::*; + use std::sync::atomic::{AtomicU64,Ordering}; + static SEQ: AtomicU64=AtomicU64::new(0); + fn fixture()->Value { + let n=SEQ.fetch_add(1,Ordering::Relaxed); + json!({"id":format!("wf-{}-{n}",std::process::id()), + "resume_dir":format!("target/workflow-test-{}-{n}",std::process::id()), + "source_revision":"v1", + "steps":[ + {"id":"choose","kind":"model","options":["chat","office"]}, + {"id":"answer","kind":"input","question":"OK?","options":["yes","no"]}, + {"id":"end","kind":"return"} + ]}) + } + + #[test] + fn nonblocking_model_then_input_then_terminal() { + let a=fixture(); + assert_eq!(open(&a).unwrap()["status"],"created"); + assert_eq!(next(&a).unwrap()["status"],"waiting_model"); + let mut c=a.clone(); + c["step_id"]=json!("choose"); + c["response"]=json!("office"); + assert_eq!(commit(&c).unwrap()["status"],"advanced"); + assert_eq!(next(&a).unwrap()["status"],"waiting_input"); + assert_eq!(commit(&c).unwrap()["status"],"already_committed"); + c["step_id"]=json!("answer"); + c["response"]=json!("yes"); + assert_eq!(commit(&c).unwrap()["status"],"advanced"); + c["step_id"]=json!("end"); + c["response"]=json!("ok"); + assert_eq!(commit(&c).unwrap()["status"],"succeeded"); + assert_eq!(next(&a).unwrap()["status"],"succeeded"); + assert_eq!(open(&a).unwrap()["status"],"succeeded"); + } + + #[test] + fn source_change_conflict_and_invalid_model_choice() { + let a=fixture(); + open(&a).unwrap(); + let mut bad=a.clone(); + bad["source_revision"]=json!("v2"); + assert_eq!(next(&bad).unwrap()["status"],"not_found_or_mismatched"); + assert_eq!(open(&bad).unwrap()["status"],"conflict"); + let mut c=a.clone(); + c["step_id"]=json!("choose"); + c["response"]=json!("chat or office"); + assert_eq!(commit(&c).unwrap()["status"],"invalid_choice"); + assert_eq!(next(&a).unwrap()["status"],"waiting_model"); + } + + #[test] + fn explicit_cancel_stops_future_commits() { + let a=fixture(); + open(&a).unwrap(); + assert_eq!(cancel(&a).unwrap()["status"],"cancelled"); + let mut c=a.clone(); + c["step_id"]=json!("choose"); + c["response"]=json!("chat"); + assert_eq!(commit(&c).unwrap()["status"],"blocked"); + } +} From 1e1f05c087e91da15b36f7310fba7a7ac965e542 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:51:59 +0800 Subject: [PATCH 39/66] feat(agent): register ABI workflow state transitions and cancellation --- plugins/agent/src/lib.rs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 9c210c8..829ccac 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -18,6 +18,7 @@ mod resume; mod route; mod sandbox; mod tools; +mod workflow; use std::collections::HashMap; use std::ffi::CString; @@ -843,6 +844,10 @@ kb_ffi!(agent_context_scope, context_scope::project, "agent_context_scope"); kb_ffi!(agent_input_open, input::input_open, "agent_input_open"); kb_ffi!(agent_input_resume, input::input_resume, "agent_input_resume"); kb_ffi!(agent_parallel_report, parallel::report, "agent_parallel_report"); +kb_ffi!(agent_workflow_open, workflow::open, "agent_workflow_open"); +kb_ffi!(agent_workflow_next, workflow::next, "agent_workflow_next"); +kb_ffi!(agent_workflow_commit, workflow::commit, "agent_workflow_commit"); +kb_ffi!(agent_workflow_cancel, workflow::cancel, "agent_workflow_cancel"); kb_ffi!(agent_error_make, error::make_error, "agent_error_make"); kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry"); kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register"); @@ -977,6 +982,10 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_input_open", "id,question,options,source_revision", agent_input_open), ("agent_input_resume", "id,reply,source_revision", agent_input_resume), ("agent_parallel_report", "results", agent_parallel_report), + ("agent_workflow_open", "id,steps,source_revision", agent_workflow_open), + ("agent_workflow_next", "id,source_revision", agent_workflow_next), + ("agent_workflow_commit", "id,step_id,response,source_revision", agent_workflow_commit), + ("agent_workflow_cancel", "id,source_revision", agent_workflow_cancel), ("agent_error_make", "code,message,category", agent_error_make), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_tools_register", "spec,specs", agent_tools_register), From 8d47507d15573defcddc139e7bcead1f1826fe1c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:52:13 +0800 Subject: [PATCH 40/66] feat(ai): expose a concise ABI-backed durable workflow library --- ext/ai/workflow.mq.md | 105 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 ext/ai/workflow.mq.md diff --git a/ext/ai/workflow.mq.md b/ext/ai/workflow.mq.md new file mode 100644 index 0000000..56ef207 --- /dev/null +++ b/ext/ai/workflow.mq.md @@ -0,0 +1,105 @@ +--- +markup: occlusion +title: Native AI workflow — durable, short, one-step-at-a-time execution +description: Plugin-managed checkpointed decision flow without an external agent runtime. +import: + plugin: lib/plugin.mq.md + json: lib/json.mq.md + flow: ext/ai/flow.mq.md +--- + +Every step is an explicit commit boundary. The plugin stores accepted outputs, +refuses stale documents and conflicting decisions, and exposes the next action. +The caller must supply trusted session, principal and source revision fields; +model text is never an identity or permission token. + +## open + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Stable run ID | +| steps | list | required | 1–128 ordered step records | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Created, resumed, or explicit conflict | + +Use `id`, `steps`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[Open durable workflow](agent_workflow_open(id=`id`, steps=`steps`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +2. * + Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +## next + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Stable run ID | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Current action or terminal state | + +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[Find the next committed boundary](agent_workflow_next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +2. * + Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +## commit + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Stable run ID | +| step_id | text | required | Exact current step | +| response | any | required | Completed step output | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Committed next step or explicit failure | + +Use `id`, `step_id`, `response`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[Validate and commit one step](agent_workflow_commit(id=`id`, step_id=`step_id`, response=`response`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +2. * + Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +## cancel + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Stable run ID | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Cancelled checkpoint status | + +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[Commit cancellation](agent_workflow_cancel(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +2. * + Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. From f818834ec1565ecff1cd3971eb5d84318d4c0bbf Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:52:35 +0800 Subject: [PATCH 41/66] test(ai): exercise ABI-only durable workflow in actual Marqdo interpreter --- tests/ext/ai-native-workflow.mq.md | 59 ++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 tests/ext/ai-native-workflow.mq.md diff --git a/tests/ext/ai-native-workflow.mq.md b/tests/ext/ai-native-workflow.mq.md new file mode 100644 index 0000000..b643ce8 --- /dev/null +++ b/tests/ext/ai-native-workflow.mq.md @@ -0,0 +1,59 @@ +--- +markup: occlusion +title: ABI-native durable agent workflow test +import: + workflow: ext/ai/workflow.mq.md + json: lib/json.mq.md + sys: lib/sys.mq.md +--- + +# main + +Offline test: the same Marqdo program advances through model choice, user +input and terminal state with plugin-owned durable checkpoints. + +**steps = > json.parse text=[{"id":"intent","kind":"model","options":["chat","office"]},{"id":"confirm","kind":"input","question":"Continue?","options":["yes","no"]},{"id":"end","kind":"return"}]** +**opened = > workflow.open id="abi_flow_ci_20261118" steps=`steps` source_revision="flow-v1"** +**o = > json.get value=`opened` key="ok"** +1. `o` + **_ = 1** +2. * + > sys.exit code=21 + +**first = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** +**first_state = > json.get value=`first` key="status"** +1. `first_state` == "waiting_model" + **_ = 1** +2. * + > sys.exit code=22 + +**c1 = > workflow.commit id="abi_flow_ci_20261118" step_id="intent" response="chat" source_revision="flow-v1"** +**done1 = > json.get value=`c1` key="ok"** +1. `done1` + **_ = 1** +2. * + > sys.exit code=23 + +**second = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** +**second_state = > json.get value=`second` key="status"** +1. `second_state` == "waiting_input" + **_ = 1** +2. * + > sys.exit code=24 + +**c2 = > workflow.commit id="abi_flow_ci_20261118" step_id="confirm" response="yes" source_revision="flow-v1"** +**done2 = > json.get value=`c2` key="ok"** +1. `done2` + **_ = 1** +2. * + > sys.exit code=25 + +**c3 = > workflow.commit id="abi_flow_ci_20261118" step_id="end" response="finished" source_revision="flow-v1"** +**complete = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** +**status = > json.get value=`complete` key="status"** +1. `status` == "succeeded" + **_ = 1** +2. * + > sys.exit code=26 + +Return *"durable-agent-flow-ok"*. From 981faac022511bee9528b5b92ee8023a3a14c59b Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:52:42 +0800 Subject: [PATCH 42/66] ci(ai): test native workflow plugin through actual Marqdo interpreter --- .github/workflows/executable-knowledge.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml index eec00f9..24a25d7 100644 --- a/.github/workflows/executable-knowledge.yml +++ b/.github/workflows/executable-knowledge.yml @@ -23,8 +23,12 @@ jobs: cargo run --locked -- check ext/ai/recovery.mq.md cargo run --locked -- check ext/ai/context.mq.md cargo run --locked -- check tests/ext/ai-native-flow.mq.md + cargo run --locked -- check ext/ai/workflow.mq.md + cargo run --locked -- check tests/ext/ai-native-workflow.mq.md - name: Native AI flow interpreter smoke (offline) - run: cargo run --locked -- run tests/ext/ai-native-flow.mq.md + run: | + cargo run --locked -- run tests/ext/ai-native-flow.mq.md + cargo run --locked -- run tests/ext/ai-native-workflow.mq.md - name: Workbench contracts (M00–M06 / F-subset) run: cargo test --test workbench_contracts --locked - name: Offline executable-knowledge gate From 0cd64a74507b41e78ccbf2c3689eb9052a6b00ac Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:53:02 +0800 Subject: [PATCH 43/66] fix(agent): persist partial child outcomes and require verified process success before workflow commit --- plugins/agent/src/workflow.rs | 53 ++++++++++++++++++++++++++++------- 1 file changed, 43 insertions(+), 10 deletions(-) diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs index d96b174..f56a126 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -167,7 +167,8 @@ fn next_doc(ckpt: &Value, id: &str, reused: bool) -> Result { let status=ckpt["status"].as_str().unwrap_or("running"); if status=="blocked" || status=="uncertain" || status=="cancelled" { return Ok(json!({"ok":false,"id":id,"status":status, - "cursor":index,"step":step,"completed":meta["completed"]})); + "cursor":index,"step":step,"completed":meta["completed"], + "partial": meta.get("partial").cloned().unwrap_or(Value::Null)})); } let waiting=match step["kind"].as_str().unwrap_or("") { "model"=>"waiting_model", @@ -234,20 +235,33 @@ pub fn commit(args: &Value) -> Result { valid["value"].clone() } "skill" => { - if response["ok"]!=true { - return Ok(json!({"ok":false,"status":"tool_not_verified", - "reason":"only verified successful tool result may be committed"})); + // A completed wait is not equivalent to a successful child process. + let exit = response.get("value").and_then(|v| v.get("code")) + .or_else(|| response.get("code")).and_then(Value::as_i64); + if response["ok"]==false || exit != Some(0) { + return Ok(json!({"ok":false, + "status":if exit.is_none() {"uncertain"} else {"failed"}, + "reason":"child process exit code zero is required before commit"})); } response.clone() } "parallel" => { - let report=parallel::report(&json!({"results":response}))?; + let report=if response["schema"]=="AgentParallelResultV1" { + response.clone() + } else { + parallel::report(&json!({"results":response}))? + }; if report["ok"]!=true { - return Ok(json!({"ok":false, - "status": if report["uncertain"].as_u64().unwrap_or(0)>0 { - "uncertain" } else {"partial"}, - "report":report, - "reason":"preserve successful children; reconcile or retry failed children separately"})); + let status=if report["uncertain"].as_u64().unwrap_or(0)>0 { + "uncertain" + } else {"blocked"}; + // Save the full manifest of successful and failed siblings before + // returning. Do not run failed/unknown children automatically. + let mut frozen=meta.clone(); + frozen["partial"]=report.clone(); + save(args,id,&frozen,status)?; + return Ok(json!({"ok":false,"status":status, + "report":report,"reason":"child results retained for reconciliation"})); } report } @@ -333,6 +347,25 @@ mod tests { assert_eq!(next(&a).unwrap()["status"],"waiting_model"); } + #[test] + fn partial_children_remain_durable_and_unknown_requires_reconciliation() { + let mut a=fixture(); + a["steps"]=json!([{"id":"batch","kind":"parallel","tasks":[{"skill":"a"},{"skill":"b"}]}]); + open(&a).unwrap(); + let mut c=a.clone(); + c["step_id"]=json!("batch"); + c["response"]=json!([ + {"ok":true,"value":{"code":0,"value":"useful"}}, + {"ok":false,"error":"connection lost"} + ]); + assert_eq!(commit(&c).unwrap()["status"],"blocked"); + let after=next(&a).unwrap(); + assert_eq!(after["status"],"blocked"); + assert_eq!(after["partial"]["succeeded"],1); + assert_eq!(after["partial"]["failed"],1); + assert_eq!(commit(&c).unwrap()["status"],"blocked"); + } + #[test] fn explicit_cancel_stops_future_commits() { let a=fixture(); From 643ea06340ae6127093ae9744e33cddd61b9e12c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:53:17 +0800 Subject: [PATCH 44/66] feat(ai): add one-step native workflow driver for model input and bounded child tasks --- ext/ai/workflow.mq.md | 58 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/ext/ai/workflow.mq.md b/ext/ai/workflow.mq.md index 56ef207..078b28c 100644 --- a/ext/ai/workflow.mq.md +++ b/ext/ai/workflow.mq.md @@ -103,3 +103,61 @@ We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))* Return *[Commit cancellation](agent_workflow_cancel(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. 2. * Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + + +## tick + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Running workflow | +| source_revision | text | required | Pinned source revision | +| registry | map | None | Trusted SKILL registry | +| model | any | None | Configured LLM | +| session_id | text | None | Host-attested session | +| principal_ref | text | None | Host-attested principal | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | New checkpoint state, or waiting_input for the UI | + +Use `id`, `source_revision`, `registry`=None, `model`=None, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +Advance at most one step. Model text is a candidate, never direct +execution. Waiting for a user returns immediately without holding a thread. +A caller repeats tick after verified completion; UI replies use commit. + +We retain **state = [Load the next action](next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))**. +We retain **status = [Read action status](json.get(value=`state`, key="status"))**. +1. `status` == "waiting_model" + We retain **step = [Read model step](json.get(value=`state`, key="step"))**. + We retain **step_id = [Read step identifier](json.get(value=`step`, key="id"))**. + We retain **prompt = [Read local prompt](json.get(value=`step`, key="prompt"))**. + We retain **options = [Read allowed decisions](json.get(value=`step`, key="options"))**. + We retain **answer = [Make a bounded choice](flow.choose(input=`prompt`, options=`options`, model=`model`))**. + We retain **valid = [Check model decision](json.get(value=`answer`, key="ok"))**. + 1. `valid` + We retain **chosen = [Read verified model answer](json.get(value=`answer`, key="value"))**. + Return *[Commit the model choice](commit(id=`id`, step_id=`step_id`, response=`chosen`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + 2. * + Return *answer*. +2. `status` == "ready_tool" + We retain **step = [Read tool step](json.get(value=`state`, key="step"))**. + We retain **kind = [Read operation kind](json.get(value=`step`, key="kind"))**. + We retain **step_id = [Read step identifier](json.get(value=`step`, key="id"))**. + 1. `kind` == "parallel" + We retain **tasks = [Read child tasks](json.get(value=`step`, key="tasks"))**. + We retain **report = [Run bounded parallel documents](flow.parallel(tasks=`tasks`))**. + Return *[Commit all child outcomes](commit(id=`id`, step_id=`step_id`, response=`report`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + 2. `kind` == "skill" + We retain **name = [Read registered skill name](json.get(value=`step`, key="skill"))**. + We retain **out = [Run registered SKILL only](flow.enter(skill=`name`, registry=`registry`))**. + Return *[Commit verified child result](commit(id=`id`, step_id=`step_id`, response=`out`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + 3. * + Return *state*. +3. `status` == "ready_return" + We retain **step = [Read return step](json.get(value=`state`, key="step"))**. + We retain **step_id = [Read step identifier](json.get(value=`step`, key="id"))**. + We retain **value = [Read final value](json.get(value=`step`, key="value"))**. + Return *[Commit the completed workflow](commit(id=`id`, step_id=`step_id`, response=`value`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +4. * + Return *state*. From f6612813e3b3630a230805c13d43c8f34c9d10f4 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:53:58 +0800 Subject: [PATCH 45/66] fix(agent): remove resume test global cwd races and make atomic temp names unique --- plugins/agent/src/resume.rs | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/plugins/agent/src/resume.rs b/plugins/agent/src/resume.rs index 25835fa..821aec1 100644 --- a/plugins/agent/src/resume.rs +++ b/plugins/agent/src/resume.rs @@ -85,6 +85,8 @@ fn ensure_dir(root: &Path) -> Result<(), String> { } /// Atomic durable write: unique temp → write → flush/fsync → rename. +static TEMP_SEQUENCE: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> { let parent = path .parent() @@ -96,7 +98,8 @@ fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> { .and_then(|s| s.to_str()) .unwrap_or("ckpt.json"), std::process::id(), - now_rfc3339().replace(':', "") + format!("{}-{}", now_rfc3339().replace(':', ""), + TEMP_SEQUENCE.fetch_add(1, std::sync::atomic::Ordering::Relaxed)) ); let tmp = parent.join(tmp_name); let text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?; @@ -396,7 +399,8 @@ mod tests { .duration_since(UNIX_EPOCH) .unwrap() .as_nanos(); - let dir = std::env::temp_dir().join(format!("marqdo-resume-{label}-{nanos}")); + // Do not mutate process-wide cwd from concurrent Rust unit tests. + let dir = PathBuf::from("target").join(format!("marqdo-resume-{label}-{nanos}")); fs::create_dir_all(&dir).unwrap(); dir } @@ -410,10 +414,7 @@ mod tests { #[test] fn atomic_v2_roundtrip_and_legacy_manual_review() { let dir = scratch("v2"); - // Use relative path via env cwd — chdir into scratch for this test. - let prev = std::env::current_dir().unwrap(); - std::env::set_current_dir(&dir).unwrap(); - let rel = "ckpts"; + let rel = dir.join("ckpts").to_string_lossy().to_string(); let saved = resume_save(&json!({ "id": "run1", "schema": "CheckpointV2", @@ -491,23 +492,20 @@ mod tests { 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); } #[test] fn corrupt_checkpoint_reports_error() { let dir = scratch("corrupt"); - let prev = std::env::current_dir().unwrap(); - std::env::set_current_dir(&dir).unwrap(); - fs::create_dir_all("ckpts").unwrap(); - fs::write("ckpts/bad.json", "{not-json").unwrap(); - let loaded = resume_load(&json!({"id": "bad", "resume_dir": "ckpts"})).unwrap(); + let ckpts = dir.join("ckpts"); + fs::create_dir_all(&ckpts).unwrap(); + fs::write(ckpts.join("bad.json"), "{not-json").unwrap(); + let loaded = resume_load(&json!({"id": "bad", "resume_dir": ckpts.to_string_lossy()})).unwrap(); assert_eq!(loaded["found"], true); assert_eq!(loaded["ok"], false); assert_eq!(loaded["error"]["code"], "checkpoint.corrupt"); assert_eq!(loaded["recovery_mode"], "manual_review"); - std::env::set_current_dir(prev).unwrap(); let _ = fs::remove_dir_all(&dir); } } From 770dee519972f7d8f9c2d1ae4d5f3b1cb481c050 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:54:06 +0800 Subject: [PATCH 46/66] fix(agent): prevent EffectLedger atomic temp collisions under parallel operations --- plugins/agent/src/effects.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/plugins/agent/src/effects.rs b/plugins/agent/src/effects.rs index 8c4ff03..0cc35ed 100644 --- a/plugins/agent/src/effects.rs +++ b/plugins/agent/src/effects.rs @@ -91,6 +91,8 @@ fn ensure_dir(root: &Path) -> Result<(), String> { fs::create_dir_all(root).map_err(|e| format!("effects mkdir: {e}")) } +static EFFECT_TEMP_SEQUENCE: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> { let parent = path .parent() @@ -102,7 +104,8 @@ fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> { .and_then(|s| s.to_str()) .unwrap_or("op.json"), std::process::id(), - now_rfc3339().replace(':', "") + format!("{}-{}", now_rfc3339().replace(':', ""), + EFFECT_TEMP_SEQUENCE.fetch_add(1, std::sync::atomic::Ordering::Relaxed)) ); let tmp = parent.join(tmp_name); let text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?; From 19f986953a4041d9e946a4b7af5bfc7fa4fbf689 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:54:21 +0800 Subject: [PATCH 47/66] test(ai): prove successful parallel child outputs survive failed sibling and checkpoint reload --- tests/ext/ai-native-workflow.mq.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/tests/ext/ai-native-workflow.mq.md b/tests/ext/ai-native-workflow.mq.md index b643ce8..0895e1c 100644 --- a/tests/ext/ai-native-workflow.mq.md +++ b/tests/ext/ai-native-workflow.mq.md @@ -56,4 +56,16 @@ input and terminal state with plugin-owned durable checkpoints. 2. * > sys.exit code=26 +**partial_steps = > json.parse text=[{"id":"children","kind":"parallel","tasks":[]}]** +**new_batch = > workflow.open id="abi_flow_partial_ci_20261118" steps=`partial_steps` source_revision="flow-v1"** +**parts = > json.parse text=[{"ok":true,"value":{"code":0,"value":"useful"}},{"ok":false,"error":"timeout"}]** +**stopped = > workflow.commit id="abi_flow_partial_ci_20261118" step_id="children" response=`parts` source_revision="flow-v1"** +**reloaded = > workflow.next id="abi_flow_partial_ci_20261118" source_revision="flow-v1"** +**partial = > json.get value=`reloaded` key="partial"** +**survivors = > json.get value=`partial` key="succeeded"** +1. `survivors` == 1 + **_ = 1** +2. * + > sys.exit code=27 + Return *"durable-agent-flow-ok"*. From cc48bf6d05ed442c0774d5cff079a9e45ae5940a Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:54:45 +0800 Subject: [PATCH 48/66] docs(agent): document plugin-only durable step state engine and safety boundaries --- doc/design/native-agent-flow-v3.md | 46 ++++++++++++++++++++++++++++-- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/doc/design/native-agent-flow-v3.md b/doc/design/native-agent-flow-v3.md index d4b37c3..54b6cf7 100644 --- a/doc/design/native-agent-flow-v3.md +++ b/doc/design/native-agent-flow-v3.md @@ -1,8 +1,9 @@ # Marqdo native agent flow — implementation contract -Status: **incremental, draft**. This document distinguishes implemented interfaces from -the required interpreter/runtime changes. Do not claim stack-level suspension or -exactly-once external writes based on a checkpoint file. +Status: **incremental, draft**. The core orchestration now has a plugin-only +alternative to interpreter-stack suspension: a durable finite step state machine +with explicit safe commit boundaries. Do not claim arbitrary stack-level +continuation or exactly-once external writes based on a checkpoint file. ## Author surface (implemented in this branch) @@ -89,3 +90,42 @@ back. On recovery, reconcile child attempts and reuse successful results. Do not merge the branch as a completed runtime refactor until the relevant runtime gates, including crash injection and multi-worker concurrency, pass. + + +## Plugin-only workflow (November 18 revision) + +The Agent ABI plugin implements `agent_workflow_open/next/commit/cancel`. +The small `ext/ai/workflow.mq.md` library wraps these primitives and provides +`tick` to execute exactly one safe decision or document task per call. +Source definitions have only five step kinds: `model`, `input`, `skill`, +`parallel` and `return`. Model text is verified against declared options. +`input` intentionally returns a waiting status; the UI supplies an answer +through `commit` on a later invocation. There is no interpreter thread to +hold and no need for a separate qdagent orchestration server. + +The checkpoint records the source revision, caller-provided session and +principal scope, next step index and the completed outputs. The same step +cannot be silently committed twice. Mixed child outcomes preserve completed +siblings in the checkpoint and **block** further automatic execution until +the unknown/failed child operations are reconciled. + +The state engine does not execute arbitrary unregistered tools directly: +`tick` delegates to existing Marqdo ABI-backed SKILL/subtask functions. +This is an implementation of **durable step-state recovery**, not a claim +of transparent recovery for a suspended foreign function or native call. +It provides the practical workflow needed for short qdagent SKILLs without +altering the Marqdo interpreter. + +### Security/reliability boundary still required for production + +- The host must attest source digest, principal, session, permissions and + registry, rather than accepting values copied from an LLM response. +- Effectful child tools must use the existing EffectLedger and external + receipt reconciliation; no automatic re-dispatch after an uncertain write. +- Cancelling a workflow checkpoint does not automatically cancel previously + spawned external children; the supervisor must propagate cancellation. +- The current task runner is step-atomic, not a durable parallel child lease + scheduler. A future plugin-only child manifest may use the host's existing + `runtime` query API, but must not bypass process.exec or file-root grants. +- Cross-process locks need a lease/owner-aware stale-lock recovery path; + a stale lock currently fails closed and requires operator review. From dd2218026976f12f89121b537ea0d71cb49a2552 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:55:11 +0800 Subject: [PATCH 49/66] feat(agent): recover failed read-only children only, preserving successful subtask results --- plugins/agent/src/workflow.rs | 125 ++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs index f56a126..62eff3c 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -279,6 +279,107 @@ pub fn commit(args: &Value) -> Result { "cursor":index+1,"value":value,"reused":false})) } +/// Produce a plan containing only previously failed *read-only* child tasks. +/// "uncertain" children and effectful plans cannot be blindly retried. +pub fn retry_plan(args: &Value) -> Result { + let id=field(args,"id")?; + let ckpt=read(args,id)?; + if ckpt["ok"]!=true || !check_context(args,&ckpt) { + return Ok(json!({"ok":false,"status":"not_found_or_mismatched"})); + } + let (meta,index)=state(&ckpt)?; + if ckpt["status"]!="blocked" { + return Ok(json!({"ok":false,"status":"not_retryable"})); + } + let step=&meta["steps"][index]; + if step["kind"]!="parallel" || step["effect_class"]!="read" + || meta["partial"]["uncertain"].as_u64().unwrap_or(1)!=0 + { + return Ok(json!({"ok":false,"status":"manual_reconciliation_required"})); + } + let Some(items)=meta["partial"]["items"].as_array() else { + return Err("partial report has no items".into()); + }; + let Some(tasks)=step["tasks"].as_array() else { + return Err("parallel plan has no tasks".into()); + }; + if items.len()!=tasks.len() { + return Err("partial report task count mismatch".into()); + } + let mut failed=Vec::new(); + let mut indices=Vec::new(); + for (i,item) in items.iter().enumerate() { + if item["index"]!=i { + return Err("out-of-order child result index".into()); + } + if item["status"]=="failed" { + failed.push(tasks[i].clone()); + indices.push(i); + } else if item["status"]!="succeeded" { + return Ok(json!({"ok":false,"status":"manual_reconciliation_required"})); + } + } + Ok(json!({"ok":true,"status":"retry_read_only", + "id":id,"step_id":step["id"],"tasks":failed,"indices":indices})) +} + +/// Merge only the failed child slots with verified new outcomes. +/// Successful results and their order remain untouched. +pub fn retry_commit(args: &Value) -> Result { + let id=field(args,"id")?; + let _guard=lock(args,id)?; + let ckpt=read(args,id)?; + if ckpt["ok"]!=true || !check_context(args,&ckpt) { + return Ok(json!({"ok":false,"status":"not_found_or_mismatched"})); + } + let (meta,index)=state(&ckpt)?; + if ckpt["status"]!="blocked" { + return Ok(json!({"ok":false,"status":"not_retryable"})); + } + let step=&meta["steps"][index]; + if step["kind"]!="parallel" || step["effect_class"]!="read" + || meta["partial"]["uncertain"].as_u64().unwrap_or(1)!=0 + { + return Ok(json!({"ok":false,"status":"manual_reconciliation_required"})); + } + let items=meta["partial"]["items"].as_array() + .ok_or("invalid partial report")?; + let incoming=args.get("results").and_then(Value::as_array) + .ok_or("retry_commit requires results list")?; + let expected=items.iter().filter(|it|it["status"]=="failed").count(); + if incoming.len()!=expected { + return Err("retry result count differs from failed child count".into()); + } + let mut next=Vec::with_capacity(items.len()); + let mut replacement=incoming.iter(); + for item in items { + if item["status"]=="succeeded" { + next.push(item["result"].clone()); + } else if item["status"]=="failed" { + next.push(replacement.next().ok_or("missing retry result")?.clone()); + } else { + return Ok(json!({"ok":false,"status":"manual_reconciliation_required"})); + } + } + let report=parallel::report(&json!({"results":next}))?; + let mut updated=meta.clone(); + if report["ok"]==true { + updated["cursor"]=json!(index+1); + updated["partial"]=Value::Null; + updated["completed"].as_array_mut().ok_or("completed not list")? + .push(json!({"step_id":step["id"],"value":report})); + let finished=index+1==updated["steps"].as_array().ok_or("steps missing")?.len(); + save(args,id,&updated,if finished {"succeeded"} else {"running"})?; + Ok(json!({"ok":true,"status":if finished {"succeeded"} else {"advanced"}, + "cursor":index+1,"result":report})) + } else { + updated["partial"]=report.clone(); + save(args,id,&updated,if report["uncertain"].as_u64().unwrap_or(0)>0 { + "uncertain" } else {"blocked"})?; + Ok(json!({"ok":false,"status":"blocked","report":report})) + } +} + pub fn cancel(args: &Value) -> Result { let id=field(args,"id")?; let _guard=lock(args,id)?; @@ -366,6 +467,30 @@ mod tests { assert_eq!(commit(&c).unwrap()["status"],"blocked"); } + #[test] + fn retries_only_failed_read_only_children_without_redoing_successes() { + let mut a=fixture(); + a["steps"]=json!([{"id":"batch","kind":"parallel","effect_class":"read", + "tasks":[{"path":"a.mq.md"},{"path":"b.mq.md"}]}]); + open(&a).unwrap(); + let mut c=a.clone(); + c["step_id"]=json!("batch"); + c["response"]=json!([ + {"ok":true,"value":{"code":0,"value":"keep"}}, + {"ok":false,"error":"temporary timeout"} + ]); + assert_eq!(commit(&c).unwrap()["status"],"blocked"); + let plan=retry_plan(&a).unwrap(); + assert_eq!(plan["indices"],json!([1])); + assert_eq!(plan["tasks"].as_array().unwrap().len(),1); + let mut retry=a.clone(); + retry["results"]=json!([{"ok":true,"value":{"code":0,"value":"fixed"}}]); + assert_eq!(retry_commit(&retry).unwrap()["status"],"succeeded"); + let out=next(&a).unwrap(); + assert_eq!(out["completed"][0]["value"]["items"][0]["result"]["value"]["value"],"keep"); + assert_eq!(out["completed"][0]["value"]["items"][1]["result"]["value"]["value"],"fixed"); + } + #[test] fn explicit_cancel_stops_future_commits() { let a=fixture(); From 6f929dc2dae8410abd8367a597c070df919f9055 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:55:19 +0800 Subject: [PATCH 50/66] feat(agent): publish safe partial fan-out recovery through Agent ABI --- plugins/agent/src/lib.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 829ccac..eaac5a9 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -848,6 +848,8 @@ kb_ffi!(agent_workflow_open, workflow::open, "agent_workflow_open"); kb_ffi!(agent_workflow_next, workflow::next, "agent_workflow_next"); kb_ffi!(agent_workflow_commit, workflow::commit, "agent_workflow_commit"); kb_ffi!(agent_workflow_cancel, workflow::cancel, "agent_workflow_cancel"); +kb_ffi!(agent_workflow_retry_plan, workflow::retry_plan, "agent_workflow_retry_plan"); +kb_ffi!(agent_workflow_retry_commit, workflow::retry_commit, "agent_workflow_retry_commit"); kb_ffi!(agent_error_make, error::make_error, "agent_error_make"); kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry"); kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register"); @@ -986,6 +988,8 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_workflow_next", "id,source_revision", agent_workflow_next), ("agent_workflow_commit", "id,step_id,response,source_revision", agent_workflow_commit), ("agent_workflow_cancel", "id,source_revision", agent_workflow_cancel), + ("agent_workflow_retry_plan", "id,source_revision", agent_workflow_retry_plan), + ("agent_workflow_retry_commit", "id,results,source_revision", agent_workflow_retry_commit), ("agent_error_make", "code,message,category", agent_error_make), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_tools_register", "spec,specs", agent_tools_register), From 8085d06124fe139f15e90d095ab84c9f20ceb417 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:55:30 +0800 Subject: [PATCH 51/66] feat(ai): expose failed-only read-only child recovery as a short Marqdo workflow --- ext/ai/workflow.mq.md | 82 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/ext/ai/workflow.mq.md b/ext/ai/workflow.mq.md index 078b28c..352b8ce 100644 --- a/ext/ai/workflow.mq.md +++ b/ext/ai/workflow.mq.md @@ -6,6 +6,7 @@ import: plugin: lib/plugin.mq.md json: lib/json.mq.md flow: ext/ai/flow.mq.md + subtask: lib/subtask.mq.md --- Every step is an explicit commit boundary. The plugin stores accepted outputs, @@ -161,3 +162,84 @@ We retain **status = [Read action status](json.get(value=`state`, key="status")) Return *[Commit the completed workflow](commit(id=`id`, step_id=`step_id`, response=`value`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. 4. * Return *state*. + + +## retry_plan + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Blocked workflow ID | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Failed-only read-task list or manual_review | + +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +Only a parallel step explicitly declared read-only and with no uncertain +effects may return a retry plan. Completed siblings are not included. + +We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[Select failed read-only children](agent_workflow_retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +2. * + Return *[Native plugin unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +## retry_commit + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Blocked workflow ID | +| results | list | required | New outcomes for failed children only | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Merged persistent report, or still blocked | + +Use `id`, `results`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +Re-use successful child results from the checkpoint. New results fill failed +slots only, in original order; a newly uncertain outcome blocks further work. + +We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[Merge verified read-only retries](agent_workflow_retry_commit(id=`id`, results=`results`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +2. * + Return *[Native plugin unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +## retry_failed + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Blocked workflow ID | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | +| limit | number | 2 | Max concurrent failed children | +| timeout_ms | number | 30000 | Child timeout | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Recovered workflow, partial results or manual review | + +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `limit`=2, `timeout_ms`=30000 as the inputs for this operation. + +Run only the failed read-only tasks returned by the native checkpoint checker. +Unknown external writes never reach this path. + +We retain **plan = [Inspect safe retry manifest](retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))**. +We retain **can_retry = [Check permitted recovery](json.get(value=`plan`, key="ok"))**. +1. `can_retry` + We retain **tasks = [Read failed-only children](json.get(value=`plan`, key="tasks"))**. + We retain **outcomes = [Execute failed read-only children only](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))**. + Return *[Merge with preserved completed children](retry_commit(id=`id`, results=`outcomes`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +2. * + Return *plan*. From 8ea56cbe308cab939b17430435b9ff34cb4c43b1 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:55:42 +0800 Subject: [PATCH 52/66] test(ai): exercise ABI failed-only recovery without executing already successful children --- tests/ext/ai-native-workflow.mq.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/tests/ext/ai-native-workflow.mq.md b/tests/ext/ai-native-workflow.mq.md index 0895e1c..ac1b0a7 100644 --- a/tests/ext/ai-native-workflow.mq.md +++ b/tests/ext/ai-native-workflow.mq.md @@ -56,7 +56,7 @@ input and terminal state with plugin-owned durable checkpoints. 2. * > sys.exit code=26 -**partial_steps = > json.parse text=[{"id":"children","kind":"parallel","tasks":[]}]** +**partial_steps = > json.parse text=[{"id":"children","kind":"parallel","effect_class":"read","tasks":[{"path":"worker-a.mq.md"},{"path":"worker-b.mq.md"}]}]** **new_batch = > workflow.open id="abi_flow_partial_ci_20261118" steps=`partial_steps` source_revision="flow-v1"** **parts = > json.parse text=[{"ok":true,"value":{"code":0,"value":"useful"}},{"ok":false,"error":"timeout"}]** **stopped = > workflow.commit id="abi_flow_partial_ci_20261118" step_id="children" response=`parts` source_revision="flow-v1"** @@ -68,4 +68,18 @@ input and terminal state with plugin-owned durable checkpoints. 2. * > sys.exit code=27 +**retry_plan = > workflow.retry_plan id="abi_flow_partial_ci_20261118" source_revision="flow-v1"** +**allowed = > json.get value=`retry_plan` key="ok"** +1. `allowed` + **_ = 1** +2. * + > sys.exit code=28 +**repaired = > json.parse text=[{"ok":true,"value":{"code":0,"value":"repaired"}}]** +**merged = > workflow.retry_commit id="abi_flow_partial_ci_20261118" results=`repaired` source_revision="flow-v1"** +**merged_ok = > json.get value=`merged` key="ok"** +1. `merged_ok` + **_ = 1** +2. * + > sys.exit code=29 + Return *"durable-agent-flow-ok"*. From e8f1a3e126bef1e8becf3a9db2345a3edaa067a5 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:56:16 +0800 Subject: [PATCH 53/66] fix(agent): deduplicate equivalent numbered and labeled user replies --- plugins/agent/src/input.rs | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/plugins/agent/src/input.rs b/plugins/agent/src/input.rs index f01a935..7e11b1e 100644 --- a/plugins/agent/src/input.rs +++ b/plugins/agent/src/input.rs @@ -152,17 +152,8 @@ pub fn input_resume(args: &Value) -> Result { return Ok(json!({"ok":false,"status":"conflict","id":id, "error":{"code":"input.scope_or_revision_changed"}})); } - if existing["status"] == "resumed" { - if existing["result"] == reply { - return Ok(json!({"ok":true,"status":"resumed","id":id, - "value":reply,"reused":true})); - } - return Ok(json!({"ok":false,"status":"conflict","id":id, - "error":{"code":"input.already_answered"}})); - } - if existing["status"] != "waiting_input" { - return Ok(json!({"ok":false,"status":"conflict","id":id})); - } + // Normalize the answer before duplicate detection: the index "2" and + // the selected label "office" must be the same committed response. let allowed = crate::choice::parse_choice(&json!({ "options": meta["options"], "reply": reply }))?; @@ -174,6 +165,17 @@ pub fn input_resume(args: &Value) -> Result { return Ok(json!({"ok":false,"status":"invalid","id":id, "error":{"code":"input.invalid_choice"}})); }; + if existing["status"] == "resumed" { + if existing["result"] == normalized { + return Ok(json!({"ok":true,"status":"resumed","id":id, + "value":normalized,"reused":true})); + } + return Ok(json!({"ok":false,"status":"conflict","id":id, + "error":{"code":"input.already_answered"}})); + } + if existing["status"] != "waiting_input" { + return Ok(json!({"ok":false,"status":"conflict","id":id})); + } let saved = resume::resume_save(&json!({ "id": id, "resume_dir": args.get("resume_dir"), "checkpoint_v2": true, @@ -212,6 +214,7 @@ mod tests { let v = json!({"id":id,"resume_dir":dir,"reply":"2", "source_revision":"v1","session_id":"s1","principal_ref":"u1"}); assert_eq!(input_resume(&v).unwrap()["value"], "office"); + assert_eq!(input_resume(&v).unwrap()["reused"], true); assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir, "reply":"office","source_revision":"v1","session_id":"s1", "principal_ref":"u1"})).unwrap()["reused"], true); From 398a0b7222e33acc046fb5801f01f7da8253152f Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:56:28 +0800 Subject: [PATCH 54/66] ci(agent): introduce focused plugin-only native workflow gate separate from long EK suite --- .github/workflows/native-ai-flow.yml | 34 ++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 .github/workflows/native-ai-flow.yml diff --git a/.github/workflows/native-ai-flow.yml b/.github/workflows/native-ai-flow.yml new file mode 100644 index 0000000..2a63f3d --- /dev/null +++ b/.github/workflows/native-ai-flow.yml @@ -0,0 +1,34 @@ +name: native-ai-flow + +on: + push: + branches: + - feat/native-ai-flow-recovery-20261118 + pull_request: + paths: + - 'plugins/agent/**' + - 'ext/ai/flow.mq.md' + - 'ext/ai/context.mq.md' + - 'ext/ai/recovery.mq.md' + - 'ext/ai/workflow.mq.md' + - 'tests/ext/ai-native-*.mq.md' + - '.github/workflows/native-ai-flow.yml' + +jobs: + agent: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + - name: Build plugin and run native tests + run: cargo test -p marqdo_plugin_agent --locked + - name: Check the public Marqdo ABI libraries + run: | + cargo run --locked -- check ext/ai/flow.mq.md + cargo run --locked -- check ext/ai/context.mq.md + cargo run --locked -- check ext/ai/recovery.mq.md + cargo run --locked -- check ext/ai/workflow.mq.md + - name: Exercise offline integration through Marqdo + run: | + cargo run --locked -- run tests/ext/ai-native-flow.mq.md + cargo run --locked -- run tests/ext/ai-native-workflow.mq.md From 6e8a62928bf0b646df1c47fcbeab1e3a8c14da60 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:56:39 +0800 Subject: [PATCH 55/66] test(ai): verify plugin-only tick returns waiting input and commits final step --- tests/ext/ai-native-workflow.mq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/ext/ai-native-workflow.mq.md b/tests/ext/ai-native-workflow.mq.md index ac1b0a7..35cccb4 100644 --- a/tests/ext/ai-native-workflow.mq.md +++ b/tests/ext/ai-native-workflow.mq.md @@ -34,7 +34,7 @@ input and terminal state with plugin-owned durable checkpoints. 2. * > sys.exit code=23 -**second = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** +**second = > workflow.tick id="abi_flow_ci_20261118" source_revision="flow-v1"** **second_state = > json.get value=`second` key="status"** 1. `second_state` == "waiting_input" **_ = 1** @@ -48,7 +48,7 @@ input and terminal state with plugin-owned durable checkpoints. 2. * > sys.exit code=25 -**c3 = > workflow.commit id="abi_flow_ci_20261118" step_id="end" response="finished" source_revision="flow-v1"** +**c3 = > workflow.tick id="abi_flow_ci_20261118" source_revision="flow-v1"** **complete = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** **status = > json.get value=`complete` key="status"** 1. `status` == "succeeded" From 6705e2e6b7443cf4a375bffa6f60176dd1730864 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:56:49 +0800 Subject: [PATCH 56/66] fix(agent): require explicit local prompt for model workflow steps --- plugins/agent/src/workflow.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs index 62eff3c..7d9f6bc 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -93,6 +93,7 @@ fn validate_steps(args: &Value) -> Result { .ok_or_else(|| "choice step requires options list".to_string())?; let _ = choice::parse_choice(&json!({"reply":"","options":options}))?; if kind == "input" { let _ = field(s, "question")?; } + if kind == "model" { let _ = field(s, "prompt")?; } } if kind == "skill" { let _ = field(s, "skill")?; } if kind == "parallel" && !s.get("tasks").is_some_and(Value::is_array) { @@ -406,7 +407,7 @@ mod tests { "resume_dir":format!("target/workflow-test-{}-{n}",std::process::id()), "source_revision":"v1", "steps":[ - {"id":"choose","kind":"model","options":["chat","office"]}, + {"id":"choose","kind":"model","prompt":"Choose a skill","options":["chat","office"]}, {"id":"answer","kind":"input","question":"OK?","options":["yes","no"]}, {"id":"end","kind":"return"} ]}) From f859e6eeea650744f5e9adb1b4132e1a621346de Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:56:55 +0800 Subject: [PATCH 57/66] test(ai): include required short model prompt in workflow fixture --- tests/ext/ai-native-workflow.mq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/ext/ai-native-workflow.mq.md b/tests/ext/ai-native-workflow.mq.md index 35cccb4..418f787 100644 --- a/tests/ext/ai-native-workflow.mq.md +++ b/tests/ext/ai-native-workflow.mq.md @@ -12,7 +12,7 @@ import: Offline test: the same Marqdo program advances through model choice, user input and terminal state with plugin-owned durable checkpoints. -**steps = > json.parse text=[{"id":"intent","kind":"model","options":["chat","office"]},{"id":"confirm","kind":"input","question":"Continue?","options":["yes","no"]},{"id":"end","kind":"return"}]** +**steps = > json.parse text=[{"id":"intent","kind":"model","prompt":"Choose next skill","options":["chat","office"]},{"id":"confirm","kind":"input","question":"Continue?","options":["yes","no"]},{"id":"end","kind":"return"}]** **opened = > workflow.open id="abi_flow_ci_20261118" steps=`steps` source_revision="flow-v1"** **o = > json.get value=`opened` key="ok"** 1. `o` From 70b88b376734be54e76a99de9cda49aea71c0cfc Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:57:06 +0800 Subject: [PATCH 58/66] security(agent): require explicit read-only classification before automatic SKILL/parallel dispatch --- plugins/agent/src/workflow.rs | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs index 7d9f6bc..41a7862 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -171,6 +171,16 @@ fn next_doc(ckpt: &Value, id: &str, reused: bool) -> Result { "cursor":index,"step":step,"completed":meta["completed"], "partial": meta.get("partial").cloned().unwrap_or(Value::Null)})); } + // Never auto-dispatch effectful or unclassified child documents. + // Those must be executed using the existing EffectLedger policy and an + // independently verified receipt, not an arbitrary model instruction. + if (step["kind"]=="skill" || step["kind"]=="parallel") + && step["effect_class"]!="read" + { + return Ok(json!({"ok":false,"id":id,"status":"manual_review", + "cursor":index,"step":step, + "reason":"automatic child dispatch requires an explicit read-only effect class"})); + } let waiting=match step["kind"].as_str().unwrap_or("") { "model"=>"waiting_model", "input"=>"waiting_input", @@ -434,6 +444,14 @@ mod tests { assert_eq!(open(&a).unwrap()["status"],"succeeded"); } + #[test] + fn unknown_and_write_effects_never_auto_dispatch() { + let mut a=fixture(); + a["steps"]=json!([{"id":"publish","kind":"skill","skill":"office"}]); + open(&a).unwrap(); + assert_eq!(next(&a).unwrap()["status"],"manual_review"); + } + #[test] fn source_change_conflict_and_invalid_model_choice() { let a=fixture(); From 90688741c5232440760b4d6c6f061d4b4645a268 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:57:37 +0800 Subject: [PATCH 59/66] feat(agent): parse bounded JSON choice envelopes without relaxing skill allowlist --- plugins/agent/src/choice.rs | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/plugins/agent/src/choice.rs b/plugins/agent/src/choice.rs index b3b8db7..cb63e68 100644 --- a/plugins/agent/src/choice.rs +++ b/plugins/agent/src/choice.rs @@ -43,8 +43,35 @@ fn strip_label(s: &str) -> &str { } } +fn structured_reply(raw: &str) -> Option { + let parsed: Value = serde_json::from_str(raw).ok()?; + if let Some(s) = parsed.as_str() { + return Some(s.to_string()); + } + if let Some(list) = parsed.as_array() { + if list.len() == 1 { + return list[0].as_str().map(str::to_string); + } + return None; + } + let map = parsed.as_object()?; + // Refuse conflicting structured decisions instead of choosing first. + let values: Vec<&str> = ["choice", "selected", "option", "选择"] + .iter() + .filter_map(|key| map.get(*key).and_then(Value::as_str)) + .collect(); + if values.is_empty() || values.iter().any(|s| *s != values[0]) { + return None; + } + Some(values[0].to_string()) +} + fn single_choice(options: &[String], reply: &str) -> Option { let raw = strip_label(strip_fence(reply)); + // Structured single-choice replies are accepted only through known fields, + // and then still validated against the caller's exact allowlist. + let decoded = structured_reply(raw); + let raw = decoded.as_deref().unwrap_or(raw); // Small models often prepend a short selection verb. Accept only the // verb followed by a complete allowed value; explanations stay invalid. let raw = raw.trim(); @@ -130,6 +157,9 @@ mod tests { assert_eq!(check("2")["value"], "office"); assert_eq!(check("我选择 chat")["value"], "chat"); assert_eq!(check("I choose office")["value"], "office"); + assert_eq!(check(r#"{"choice":"chat"}"#)["value"], "chat"); + assert_eq!(check("[\"office\"]")["value"], "office"); + assert_eq!(check("```json\n{\"selected\":\"office\"}\n```")["value"], "office"); } #[test] @@ -141,6 +171,13 @@ mod tests { } } + #[test] + fn refuses_conflicting_structured_decisions() { + assert_eq!(check(r#"{"choice":"chat","option":"office"}"#)["ok"], false); + assert_eq!(check(r#"{"choice":"../private.mq.md"}"#)["ok"], false); + assert_eq!(check(r#"["chat","office"]"#)["ok"], false); + } + #[test] fn rejects_invalid_options_before_parsing() { for options in [ From 3ce59a4da8f6e72d5a91daa44cad8a62d935d39a Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:57:47 +0800 Subject: [PATCH 60/66] test(ai): verify JSON-formatted small-model option parsing from Marqdo --- tests/ext/ai-native-flow.mq.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/tests/ext/ai-native-flow.mq.md b/tests/ext/ai-native-flow.mq.md index cce2a01..c8fa5aa 100644 --- a/tests/ext/ai-native-flow.mq.md +++ b/tests/ext/ai-native-flow.mq.md @@ -22,6 +22,13 @@ rather than guessing another SKILL or importing the full document. 2. * > sys.exit code=11 +**structured = > flow.parse_choice reply="{\"choice\":\"chat\"}" options=`opts`** +**structure_value = > json.get value=`structured` key="value"** +1. `structure_value` == "chat" + **_ = 1** +2. * + > sys.exit code=16 + **invalid = > flow.parse_choice reply="chat 或 office" options=`opts`** **not_ok = > json.get value=`invalid` key="ok"** 1. `not_ok` From 8a66f803cb88c49a1af3c1a549ae51434217edcf Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:59:16 +0800 Subject: [PATCH 61/66] feat(agent): add validated forward-only branching from model choices to registered SKILL steps --- plugins/agent/src/workflow.rs | 80 ++++++++++++++++++++++++++++++++--- 1 file changed, 74 insertions(+), 6 deletions(-) diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs index 41a7862..dff495e 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -100,9 +100,52 @@ fn validate_steps(args: &Value) -> Result { return Err("parallel step requires tasks array".into()); } } + // Resolve all branch targets against frozen, forward-only step IDs. + for (i, s) in steps.iter().enumerate() { + let targets = s.get("next").and_then(Value::as_str).into_iter() + .chain(s.get("routes").and_then(Value::as_object) + .into_iter().flat_map(|m| m.values().filter_map(Value::as_str))); + for target in targets { + let position = steps.iter().position(|x|x["id"]==target) + .ok_or_else(|| format!("unknown workflow target: {target}"))?; + if position <= i { + return Err("workflow routes must move forward to avoid loops".into()); + } + } + if let Some(routes)=s.get("routes").and_then(Value::as_object) { + if !matches!(s["kind"].as_str(),Some("model"|"input")) { + return Err("only choice steps may declare routes".into()); + } + for key in routes.keys() { + if !s["options"].as_array().is_some_and(|opts| + opts.iter().any(|x|x==key.as_str())) { + return Err("route label is not a declared choice".into()); + } + } + } + } Ok(Value::Array(steps.clone())) } +fn advance_cursor(step:&Value, value:&Value, steps:&[Value], current:usize)->Result { + let target=if let Some(routes)=step.get("routes").and_then(Value::as_object) { + let label=value.as_str().ok_or("routed choice must return a text label")?; + Some(routes.get(label).and_then(Value::as_str) + .ok_or("chosen option is missing a declared route")?) + } else { + step.get("next").and_then(Value::as_str) + }; + match target { + None=>Ok(current+1), + Some(name)=> { + let n=steps.iter().position(|s|s["id"]==name) + .ok_or("unknown target after checkpoint recovery")?; + if n<=current {return Err("cyclic route refused".into())} + Ok(n) + } + } +} + fn state(ckpt: &Value) -> Result<(&Value,usize),String> { let meta = ckpt.get("meta").ok_or("missing workflow metadata")?; if meta.get("kind").and_then(Value::as_str) != Some("MarqdoAgentFlowV1") { @@ -279,15 +322,16 @@ pub fn commit(args: &Value) -> Result { "return" => response.clone(), _ => return Err("invalid step kind".into()), }; + let target=advance_cursor(step,&value,steps,index)?; let mut new_meta=meta.clone(); - new_meta["cursor"]=json!(index+1); + new_meta["cursor"]=json!(target); new_meta["completed"].as_array_mut().ok_or("completed not array")? .push(json!({"step_id":step_id,"value":value})); - let terminal=index+1==steps.len(); + let terminal=target==steps.len(); save(args,id,&new_meta,if terminal {"succeeded"} else {"running"})?; Ok(json!({"ok":true,"id":id, "status":if terminal {"succeeded"} else {"advanced"}, - "cursor":index+1,"value":value,"reused":false})) + "cursor":target,"value":value,"reused":false})) } /// Produce a plan containing only previously failed *read-only* child tasks. @@ -375,14 +419,16 @@ pub fn retry_commit(args: &Value) -> Result { let report=parallel::report(&json!({"results":next}))?; let mut updated=meta.clone(); if report["ok"]==true { - updated["cursor"]=json!(index+1); + let target=advance_cursor(step,&report, + updated["steps"].as_array().ok_or("steps missing")?,index)?; + updated["cursor"]=json!(target); updated["partial"]=Value::Null; updated["completed"].as_array_mut().ok_or("completed not list")? .push(json!({"step_id":step["id"],"value":report})); - let finished=index+1==updated["steps"].as_array().ok_or("steps missing")?.len(); + let finished=target==updated["steps"].as_array().ok_or("steps missing")?.len(); save(args,id,&updated,if finished {"succeeded"} else {"running"})?; Ok(json!({"ok":true,"status":if finished {"succeeded"} else {"advanced"}, - "cursor":index+1,"result":report})) + "cursor":target,"result":report})) } else { updated["partial"]=report.clone(); save(args,id,&updated,if report["uncertain"].as_u64().unwrap_or(0)>0 { @@ -452,6 +498,28 @@ mod tests { assert_eq!(next(&a).unwrap()["status"],"manual_review"); } + #[test] + fn routes_skip_unselected_skill_branches() { + let mut a=fixture(); + a["steps"]=json!([ + {"id":"decide","kind":"model","prompt":"Pick","options":["chat","office"], + "routes":{"chat":"chat_skill","office":"office_skill"}}, + {"id":"chat_skill","kind":"skill","skill":"chat","effect_class":"read","next":"done"}, + {"id":"office_skill","kind":"skill","skill":"office","effect_class":"read","next":"done"}, + {"id":"done","kind":"return"} + ]); + open(&a).unwrap(); + let mut c=a.clone(); + c["step_id"]=json!("decide"); + c["response"]=json!("office"); + assert_eq!(commit(&c).unwrap()["cursor"],2); + assert_eq!(next(&a).unwrap()["step"]["id"],"office_skill"); + c["step_id"]=json!("office_skill"); + c["response"]=json!({"ok":true,"value":{"code":0}}); + assert_eq!(commit(&c).unwrap()["cursor"],3); + assert_eq!(next(&a).unwrap()["step"]["id"],"done"); + } + #[test] fn source_change_conflict_and_invalid_model_choice() { let a=fixture(); From 92c3f800554adb44a6205ebbc88a713de07812c1 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:59:27 +0800 Subject: [PATCH 62/66] fix(agent): compare branch labels using explicit text conversion --- plugins/agent/src/workflow.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs index dff495e..5e10548 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -118,7 +118,7 @@ fn validate_steps(args: &Value) -> Result { } for key in routes.keys() { if !s["options"].as_array().is_some_and(|opts| - opts.iter().any(|x|x==key.as_str())) { + opts.iter().any(|x|x.as_str()==Some(key.as_str()))) { return Err("route label is not a declared choice".into()); } } From 58b65215a1bd14c65aaa2433feb18e38955c49fa Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 10:16:43 +0800 Subject: [PATCH 63/66] test(agent): show the failed native choice result in interpreter smoke diagnostics --- tests/ext/ai-native-flow.mq.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/ext/ai-native-flow.mq.md b/tests/ext/ai-native-flow.mq.md index c8fa5aa..f5598c5 100644 --- a/tests/ext/ai-native-flow.mq.md +++ b/tests/ext/ai-native-flow.mq.md @@ -20,6 +20,8 @@ rather than guessing another SKILL or importing the full document. 1. `value` == "office" **_ = 1** 2. * + **debug_pick = > json.stringify value=`pick`** + > print text=`debug_pick` > sys.exit code=11 **structured = > flow.parse_choice reply="{\"choice\":\"chat\"}" options=`opts`** From 23229a6ac97d928fd7a02f0fdeb02564dbd5b20d Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 10:17:44 +0800 Subject: [PATCH 64/66] ci(agent): permit native ABI loading in offline Agent integration tests --- .github/workflows/native-ai-flow.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/native-ai-flow.yml b/.github/workflows/native-ai-flow.yml index 2a63f3d..7496adc 100644 --- a/.github/workflows/native-ai-flow.yml +++ b/.github/workflows/native-ai-flow.yml @@ -30,5 +30,5 @@ jobs: cargo run --locked -- check ext/ai/workflow.mq.md - name: Exercise offline integration through Marqdo run: | - cargo run --locked -- run tests/ext/ai-native-flow.mq.md - cargo run --locked -- run tests/ext/ai-native-workflow.mq.md + cargo run --locked -- run tests/ext/ai-native-flow.mq.md --effects plugin,fs.write + cargo run --locked -- run tests/ext/ai-native-workflow.mq.md --effects plugin,fs.write From 8e437e2cd361bce7f9a98c034500cdb0655bdb1c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 10:17:47 +0800 Subject: [PATCH 65/66] ci(agent): permit native ABI loading in offline Agent integration tests --- .github/workflows/executable-knowledge.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml index 24a25d7..430e086 100644 --- a/.github/workflows/executable-knowledge.yml +++ b/.github/workflows/executable-knowledge.yml @@ -27,8 +27,8 @@ jobs: cargo run --locked -- check tests/ext/ai-native-workflow.mq.md - name: Native AI flow interpreter smoke (offline) run: | - cargo run --locked -- run tests/ext/ai-native-flow.mq.md - cargo run --locked -- run tests/ext/ai-native-workflow.mq.md + cargo run --locked -- run tests/ext/ai-native-flow.mq.md --effects plugin,fs.write + cargo run --locked -- run tests/ext/ai-native-workflow.mq.md --effects plugin,fs.write - name: Workbench contracts (M00–M06 / F-subset) run: cargo test --test workbench_contracts --locked - name: Offline executable-knowledge gate From 38c07d9a0e710190f1be58af0c2c567c9fdaa84c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 11:57:12 +0800 Subject: [PATCH 66/66] feat(agent): add workflow inspection and durable isolation - add agent_workflow_inspect/list primitives and ext/ai wrappers - expose host-relative resume_dir on every workflow operation - make offline workflow fixture repeatable with a timestamped run id - fix flow.choose branch scoping contract diagnostic - build the agent cdylib and drop the removed run --effects flag in CI --- .github/workflows/executable-knowledge.yml | 6 +- .github/workflows/native-ai-flow.yml | 12 ++- .gitignore | 2 + CHANGELOG.md | 15 +++ doc/design/native-agent-flow-v3.md | 17 ++- ext/ai/flow.mq.md | 28 ++--- ext/ai/index.mq.md | 4 +- ext/ai/workflow.mq.md | 120 +++++++++++++++++---- plugins/agent/src/lib.rs | 16 +-- plugins/agent/src/workflow.rs | 88 +++++++++++++++ tests/ext/ai-native-workflow.mq.md | 65 ++++++++--- 11 files changed, 308 insertions(+), 65 deletions(-) diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml index 430e086..e6cc297 100644 --- a/.github/workflows/executable-knowledge.yml +++ b/.github/workflows/executable-knowledge.yml @@ -26,9 +26,11 @@ jobs: cargo run --locked -- check ext/ai/workflow.mq.md cargo run --locked -- check tests/ext/ai-native-workflow.mq.md - name: Native AI flow interpreter smoke (offline) + env: + MARQDO_AGENT_PLUGIN: ${{ github.workspace }}/target/debug/libagent.so run: | - cargo run --locked -- run tests/ext/ai-native-flow.mq.md --effects plugin,fs.write - cargo run --locked -- run tests/ext/ai-native-workflow.mq.md --effects plugin,fs.write + cargo run --locked -- run tests/ext/ai-native-flow.mq.md + cargo run --locked -- run tests/ext/ai-native-workflow.mq.md - name: Workbench contracts (M00–M06 / F-subset) run: cargo test --test workbench_contracts --locked - name: Offline executable-knowledge gate diff --git a/.github/workflows/native-ai-flow.yml b/.github/workflows/native-ai-flow.yml index 7496adc..da1c944 100644 --- a/.github/workflows/native-ai-flow.yml +++ b/.github/workflows/native-ai-flow.yml @@ -20,7 +20,9 @@ jobs: steps: - uses: actions/checkout@v4 - uses: dtolnay/rust-toolchain@stable - - name: Build plugin and run native tests + - name: Build the agent plugin + run: cargo build -p marqdo_plugin_agent --locked + - name: Run native agent and workflow tests run: cargo test -p marqdo_plugin_agent --locked - name: Check the public Marqdo ABI libraries run: | @@ -28,7 +30,11 @@ jobs: cargo run --locked -- check ext/ai/context.mq.md cargo run --locked -- check ext/ai/recovery.mq.md cargo run --locked -- check ext/ai/workflow.mq.md + cargo run --locked -- check tests/ext/ai-native-flow.mq.md + cargo run --locked -- check tests/ext/ai-native-workflow.mq.md - name: Exercise offline integration through Marqdo + env: + MARQDO_AGENT_PLUGIN: ${{ github.workspace }}/target/debug/libagent.so run: | - cargo run --locked -- run tests/ext/ai-native-flow.mq.md --effects plugin,fs.write - cargo run --locked -- run tests/ext/ai-native-workflow.mq.md --effects plugin,fs.write + cargo run --locked -- run tests/ext/ai-native-flow.mq.md + cargo run --locked -- run tests/ext/ai-native-workflow.mq.md diff --git a/.gitignore b/.gitignore index 919c8d5..94642b7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,7 @@ /target/ /dist/ +# Plugin unit tests use package-relative scratch checkpoints. +/plugins/agent/target/ # Copied by gold harness for ABI plugins /tests/lib/demo.dll diff --git a/CHANGELOG.md b/CHANGELOG.md index b910e1a..5f3f859 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,21 @@ ## Unreleased +### Added + +- `ext/ai/workflow` now exposes read-only `inspect`/`list`, a host-relative + `resume_dir` on every operation, and repeatable offline workflow fixtures. +- Agent ABI registers `agent_workflow_inspect` and `agent_workflow_list`. +- AI 工作流拓展库新增只读 `inspect`/`list`、各操作的 `resume_dir` 隔离, + 离线集成夹具改为按时间戳生成运行 ID,可重复执行。 + +### Fixed + +- `flow.choose` no longer leaks a branch-local `parsed` value into the function + contract; the repaired-choice path is fully scoped. +- CI builds the agent cdylib and runs offline integration without the removed + `run --effects` flag, using `MARQDO_AGENT_PLUGIN` instead. + ## v2.7.1 — 2026-11-11 CLI 修复发布:View 实际逻辑的手动开合不再被布局重排或运行结果刷新覆盖;函数、链接、列表和记录按内容排版,手机详情整行展示。核心仍为 19 个构造;拓展库保留 2.7.0。 diff --git a/doc/design/native-agent-flow-v3.md b/doc/design/native-agent-flow-v3.md index 54b6cf7..ce85b0c 100644 --- a/doc/design/native-agent-flow-v3.md +++ b/doc/design/native-agent-flow-v3.md @@ -16,10 +16,16 @@ continuation or exactly-once external writes based on a checkpoint file. | ext/ai/flow.mq.md | start/wait/parallel | Existing Marqdo subtask scheduler, failure-preserving parallel result aggregation | | ext/ai/flow.mq.md | enter | Resolve only author-supplied registered skill name, run via standard subtask path | | ext/ai/recovery.mq.md | decide/save/load | Native error policy and CheckpointV2; no implicit unsafe re-execution | +| ext/ai/workflow.mq.md | open/next/commit/cancel | Durable forward-only step machine with per-step commit boundaries | +| ext/ai/workflow.mq.md | inspect/list | Read-only progress summary and checkpoint discovery scoped by session/principal | +| ext/ai/workflow.mq.md | tick/retry_plan/retry_commit/retry_failed | One-step execution and failed-only read-only recovery | The native agent plugin provides `agent_choice_parse`, `agent_context_scope`, -`agent_input_open`, `agent_input_resume` and `agent_parallel_report`. +`agent_input_open`, `agent_input_resume`, `agent_parallel_report`, and the +`agent_workflow_*` primitives including `inspect` and `list`. Plugin errors must be visible, never converted into a fabricated successful answer. +All workflow wrappers accept a host-relative `resume_dir`, so tests and callers +can isolate checkpoints instead of sharing the default `.marqdo/agent-resume`. ## Invariants @@ -94,9 +100,12 @@ runtime gates, including crash injection and multi-worker concurrency, pass. ## Plugin-only workflow (November 18 revision) -The Agent ABI plugin implements `agent_workflow_open/next/commit/cancel`. -The small `ext/ai/workflow.mq.md` library wraps these primitives and provides -`tick` to execute exactly one safe decision or document task per call. +The Agent ABI plugin implements +`agent_workflow_open/next/inspect/list/commit/cancel` plus the failed-only +retry primitives. The small `ext/ai/workflow.mq.md` library wraps these +primitives and provides `tick` to execute exactly one safe decision or document +task per call. `inspect` and `list` are strictly read-only: they report progress +or discover checkpoints without advancing a cursor or running a step. Source definitions have only five step kinds: `model`, `input`, `skill`, `parallel` and `return`. Model text is verified against declared options. `input` intentionally returns a waiting status; the UI supplies an answer diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index 346fd69..a005f15 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -65,20 +65,20 @@ We retain **err = [Check model transport error](json.get(value=`turn`, key="erro 2. * We retain **reply = [Read model answer](json.get(value=`turn`, key="text"))**. We retain **parsed = [Validate the model reply](parse_choice(reply=`reply`, options=`options`))**. -We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. -1. `ok` - Return *parsed*. -2. `repair` - We retain **fix = "Your answer was not an exact allowed option. Return only ONE option name from:\n" + opts**. - We retain **fixed = [Retry the format only once](m.ask(prompt=`fix`))**. - We retain **repair_error = [Read transport error](json.get(value=`fixed`, key="error"))**. - 1. `repair_error` - Return *fixed*. - 2. * - We retain **again = [Read corrected answer](json.get(value=`fixed`, key="text"))**. - Return *[Validate the repaired reply](parse_choice(reply=`again`, options=`options`))*. -3. * - Return *parsed*. + We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. + 1. `ok` + Return *parsed*. + 2. `repair` + We retain **fix = "Your answer was not an exact allowed option. Return only ONE option name from:\n" + opts**. + We retain **fixed = [Retry the format only once](m.ask(prompt=`fix`))**. + We retain **repair_error = [Read transport error](json.get(value=`fixed`, key="error"))**. + 1. `repair_error` + Return *fixed*. + 2. * + We retain **again = [Read corrected answer](json.get(value=`fixed`, key="text"))**. + Return *[Validate the repaired reply](parse_choice(reply=`again`, options=`options`))*. + 3. * + Return *parsed*. ## parallel diff --git a/ext/ai/index.mq.md b/ext/ai/index.mq.md index 197615e..0015ff9 100644 --- a/ext/ai/index.mq.md +++ b/ext/ai/index.mq.md @@ -10,7 +10,9 @@ stream collection and usage; [provider adapters](llm/index.mq.md) describe OpenA and Ollama requests. [Agents](agent.mq.md) own call-site context, the explicit tool registry, policy routing, observations, workbook planning and continuation. [CoW trials](sandbox.mq.md) own isolated file changes and promotion. [Native flow](flow.mq.md) provides short, verified model choices and bounded document -concurrency; [context](context.mq.md) packs explicit source scopes; [recovery](recovery.mq.md) +concurrency; [workflow](workflow.mq.md) drives a durable forward-only step plan with +`inspect`/`list` progress queries and failed-only read recovery; [context](context.mq.md) +packs explicit source scopes; [recovery](recovery.mq.md) uses the native error policy and versioned checkpoints. These are lightweight interfaces, not a second agent runtime. [Step routing](policies/step-route.mq.md) is readable diff --git a/ext/ai/workflow.mq.md b/ext/ai/workflow.mq.md index 352b8ce..52014df 100644 --- a/ext/ai/workflow.mq.md +++ b/ext/ai/workflow.mq.md @@ -12,7 +12,8 @@ import: Every step is an explicit commit boundary. The plugin stores accepted outputs, refuses stale documents and conflicting decisions, and exposes the next action. The caller must supply trusted session, principal and source revision fields; -model text is never an identity or permission token. +model text is never an identity or permission token. `resume_dir` is a +host-relative checkpoint directory, never an absolute client path. ## open @@ -23,17 +24,22 @@ model text is never an identity or permission token. | source_revision | text | required | Pinned source revision | | session_id | text | None | Trusted session | | principal_ref | text | None | Trusted principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | Created, resumed, or explicit conflict | -Use `id`, `steps`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. +Use `id`, `steps`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. + +Opening the same ID with the same steps, source revision, session and principal +returns the current action instead of resetting progress. Reusing an ID with a +different plan or identity fails closed. We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. 1. `p` We **[Load Agent ABI plugin](plugin.load(path=`p`))**. - Return *[Open durable workflow](agent_workflow_open(id=`id`, steps=`steps`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Open durable workflow](agent_workflow_open(id=`id`, steps=`steps`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. @@ -45,17 +51,75 @@ We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))* | source_revision | text | required | Pinned source revision | | session_id | text | None | Trusted session | | principal_ref | text | None | Trusted principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | Current action or terminal state | -Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. + +`next` is read-only: it does not call a model, run a child document or consume +the current step. Stopped states (`blocked`, `uncertain`, `cancelled`) and +unclassified child effects are reported explicitly. We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. 1. `p` We **[Load Agent ABI plugin](plugin.load(path=`p`))**. - Return *[Find the next committed boundary](agent_workflow_next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Find the next committed boundary](agent_workflow_next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. +2. * + Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +## inspect + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Stable run ID | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Progress summary with cursor, step and partial results | + +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. + +Use inspect for a UI progress panel or an operator audit. It returns the +durable checkpoint `status`, the next `action` (for example `waiting_model`), +cursor, total and completed step counts, the current step, and retained partial +child results without advancing the workflow. + +We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[Read workflow progress](agent_workflow_inspect(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. +2. * + Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +## list + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| session_id | text | None | Trusted session filter | +| principal_ref | text | None | Trusted principal filter | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Workflow summaries, newest metadata included separately | + +Use `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. + +Only native workflow checkpoints are listed; unrelated resume records and +corrupt files are omitted. Pass host-attested filters to keep one session or +principal from seeing another's run identifiers. + +We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[List workflow checkpoints](agent_workflow_list(session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. @@ -69,17 +133,21 @@ We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))* | source_revision | text | required | Pinned source revision | | session_id | text | None | Trusted session | | principal_ref | text | None | Trusted principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | Committed next step or explicit failure | -Use `id`, `step_id`, `response`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. +Use `id`, `step_id`, `response`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. + +A completed step cannot be committed twice. Replaying the same value returns +the already-committed result; a different value for the same step conflicts. We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. 1. `p` We **[Load Agent ABI plugin](plugin.load(path=`p`))**. - Return *[Validate and commit one step](agent_workflow_commit(id=`id`, step_id=`step_id`, response=`response`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Validate and commit one step](agent_workflow_commit(id=`id`, step_id=`step_id`, response=`response`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. @@ -91,17 +159,21 @@ We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))* | source_revision | text | required | Pinned source revision | | session_id | text | None | Trusted session | | principal_ref | text | None | Trusted principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | Cancelled checkpoint status | -Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. + +Cancelling prevents future commits. It does not claim that children already +started by the supervisor were rolled back. We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. 1. `p` We **[Load Agent ABI plugin](plugin.load(path=`p`))**. - Return *[Commit cancellation](agent_workflow_cancel(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Commit cancellation](agent_workflow_cancel(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. @@ -116,18 +188,19 @@ We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))* | model | any | None | Configured LLM | | session_id | text | None | Host-attested session | | principal_ref | text | None | Host-attested principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | New checkpoint state, or waiting_input for the UI | -Use `id`, `source_revision`, `registry`=None, `model`=None, `session_id`=None, `principal_ref`=None as the inputs for this operation. +Use `id`, `source_revision`, `registry`=None, `model`=None, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. Advance at most one step. Model text is a candidate, never direct execution. Waiting for a user returns immediately without holding a thread. A caller repeats tick after verified completion; UI replies use commit. -We retain **state = [Load the next action](next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))**. +We retain **state = [Load the next action](next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))**. We retain **status = [Read action status](json.get(value=`state`, key="status"))**. 1. `status` == "waiting_model" We retain **step = [Read model step](json.get(value=`state`, key="step"))**. @@ -138,7 +211,7 @@ We retain **status = [Read action status](json.get(value=`state`, key="status")) We retain **valid = [Check model decision](json.get(value=`answer`, key="ok"))**. 1. `valid` We retain **chosen = [Read verified model answer](json.get(value=`answer`, key="value"))**. - Return *[Commit the model choice](commit(id=`id`, step_id=`step_id`, response=`chosen`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Commit the model choice](commit(id=`id`, step_id=`step_id`, response=`chosen`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *answer*. 2. `status` == "ready_tool" @@ -148,18 +221,18 @@ We retain **status = [Read action status](json.get(value=`state`, key="status")) 1. `kind` == "parallel" We retain **tasks = [Read child tasks](json.get(value=`step`, key="tasks"))**. We retain **report = [Run bounded parallel documents](flow.parallel(tasks=`tasks`))**. - Return *[Commit all child outcomes](commit(id=`id`, step_id=`step_id`, response=`report`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Commit all child outcomes](commit(id=`id`, step_id=`step_id`, response=`report`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. `kind` == "skill" We retain **name = [Read registered skill name](json.get(value=`step`, key="skill"))**. We retain **out = [Run registered SKILL only](flow.enter(skill=`name`, registry=`registry`))**. - Return *[Commit verified child result](commit(id=`id`, step_id=`step_id`, response=`out`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Commit verified child result](commit(id=`id`, step_id=`step_id`, response=`out`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 3. * Return *state*. 3. `status` == "ready_return" We retain **step = [Read return step](json.get(value=`state`, key="step"))**. We retain **step_id = [Read step identifier](json.get(value=`step`, key="id"))**. We retain **value = [Read final value](json.get(value=`step`, key="value"))**. - Return *[Commit the completed workflow](commit(id=`id`, step_id=`step_id`, response=`value`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Commit the completed workflow](commit(id=`id`, step_id=`step_id`, response=`value`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 4. * Return *state*. @@ -172,12 +245,13 @@ We retain **status = [Read action status](json.get(value=`state`, key="status")) | source_revision | text | required | Pinned source revision | | session_id | text | None | Trusted session | | principal_ref | text | None | Trusted principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | Failed-only read-task list or manual_review | -Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. Only a parallel step explicitly declared read-only and with no uncertain effects may return a retry plan. Completed siblings are not included. @@ -185,7 +259,7 @@ effects may return a retry plan. Completed siblings are not included. We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**. 1. `p` We **[Load Agent ABI plugin](plugin.load(path=`p`))**. - Return *[Select failed read-only children](agent_workflow_retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Select failed read-only children](agent_workflow_retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *[Native plugin unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. @@ -198,12 +272,13 @@ We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**. | source_revision | text | required | Pinned source revision | | session_id | text | None | Trusted session | | principal_ref | text | None | Trusted principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | Merged persistent report, or still blocked | -Use `id`, `results`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. +Use `id`, `results`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. Re-use successful child results from the checkpoint. New results fill failed slots only, in original order; a newly uncertain outcome blocks further work. @@ -211,7 +286,7 @@ slots only, in original order; a newly uncertain outcome blocks further work. We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**. 1. `p` We **[Load Agent ABI plugin](plugin.load(path=`p`))**. - Return *[Merge verified read-only retries](agent_workflow_retry_commit(id=`id`, results=`results`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Merge verified read-only retries](agent_workflow_retry_commit(id=`id`, results=`results`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *[Native plugin unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. @@ -225,21 +300,22 @@ We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**. | principal_ref | text | None | Trusted principal | | limit | number | 2 | Max concurrent failed children | | timeout_ms | number | 30000 | Child timeout | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | Recovered workflow, partial results or manual review | -Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `limit`=2, `timeout_ms`=30000 as the inputs for this operation. +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `limit`=2, `timeout_ms`=30000, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. Run only the failed read-only tasks returned by the native checkpoint checker. Unknown external writes never reach this path. -We retain **plan = [Inspect safe retry manifest](retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))**. +We retain **plan = [Inspect safe retry manifest](retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))**. We retain **can_retry = [Check permitted recovery](json.get(value=`plan`, key="ok"))**. 1. `can_retry` We retain **tasks = [Read failed-only children](json.get(value=`plan`, key="tasks"))**. We retain **outcomes = [Execute failed read-only children only](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))**. - Return *[Merge with preserved completed children](retry_commit(id=`id`, results=`outcomes`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Merge with preserved completed children](retry_commit(id=`id`, results=`outcomes`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *plan*. diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index eaac5a9..9234f45 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -846,6 +846,8 @@ kb_ffi!(agent_input_resume, input::input_resume, "agent_input_resume"); kb_ffi!(agent_parallel_report, parallel::report, "agent_parallel_report"); kb_ffi!(agent_workflow_open, workflow::open, "agent_workflow_open"); kb_ffi!(agent_workflow_next, workflow::next, "agent_workflow_next"); +kb_ffi!(agent_workflow_inspect, workflow::inspect, "agent_workflow_inspect"); +kb_ffi!(agent_workflow_list, workflow::list, "agent_workflow_list"); kb_ffi!(agent_workflow_commit, workflow::commit, "agent_workflow_commit"); kb_ffi!(agent_workflow_cancel, workflow::cancel, "agent_workflow_cancel"); kb_ffi!(agent_workflow_retry_plan, workflow::retry_plan, "agent_workflow_retry_plan"); @@ -984,12 +986,14 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_input_open", "id,question,options,source_revision", agent_input_open), ("agent_input_resume", "id,reply,source_revision", agent_input_resume), ("agent_parallel_report", "results", agent_parallel_report), - ("agent_workflow_open", "id,steps,source_revision", agent_workflow_open), - ("agent_workflow_next", "id,source_revision", agent_workflow_next), - ("agent_workflow_commit", "id,step_id,response,source_revision", agent_workflow_commit), - ("agent_workflow_cancel", "id,source_revision", agent_workflow_cancel), - ("agent_workflow_retry_plan", "id,source_revision", agent_workflow_retry_plan), - ("agent_workflow_retry_commit", "id,results,source_revision", agent_workflow_retry_commit), + ("agent_workflow_open", "id,steps,source_revision,session_id,principal_ref,resume_dir", agent_workflow_open), + ("agent_workflow_next", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_next), + ("agent_workflow_inspect", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_inspect), + ("agent_workflow_list", "session_id,principal_ref,resume_dir", agent_workflow_list), + ("agent_workflow_commit", "id,step_id,response,source_revision,session_id,principal_ref,resume_dir", agent_workflow_commit), + ("agent_workflow_cancel", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_cancel), + ("agent_workflow_retry_plan", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_retry_plan), + ("agent_workflow_retry_commit", "id,results,source_revision,session_id,principal_ref,resume_dir", agent_workflow_retry_commit), ("agent_error_make", "code,message,category", agent_error_make), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_tools_register", "spec,specs", agent_tools_register), diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs index 5e10548..f7d3578 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -245,6 +245,71 @@ pub fn next(args: &Value) -> Result { next_doc(&ckpt,id,false) } +/// Read a workflow summary without advancing it or running any step. +/// The caller-supplied identity must match the checkpoint, exactly like next. +pub fn inspect(args:&Value)->Result { + let id=field(args,"id")?; + let ckpt=read(args,id)?; + if ckpt["ok"]!=true || !check_context(args,&ckpt) { + return Ok(json!({"ok":false,"id":id,"status":"not_found_or_mismatched"})); + } + let (meta,index)=state(&ckpt)?; + let steps=meta["steps"].as_array().ok_or("invalid steps")?; + let completed=meta["completed"].as_array().ok_or("invalid completed")?; + // `status` is the durable checkpoint status; `action` is what tick would + // observe next (waiting_model, waiting_input, ready_tool, ...). + let action=next_doc(&ckpt,id,false)?.get("status").cloned().unwrap_or(Value::Null); + Ok(json!({ + "ok":true,"id":id, + "status":ckpt["status"].as_str().unwrap_or("running"), + "action":action, + "cursor":index, + "total_steps":steps.len(), + "completed_steps":completed.len(), + "completed":meta["completed"], + "step":steps.get(index).cloned().unwrap_or(Value::Null), + "partial":meta.get("partial").cloned().unwrap_or(Value::Null), + "identity":meta["identity"], + "updated_at":ckpt.get("updated_at").cloned().unwrap_or(Value::Null) + })) +} + +/// List workflow checkpoints in the (host-relative) resume directory. +/// Non-workflow checkpoints and corrupt entries are omitted. When the caller +/// supplies an attested session or principal, only matching runs are returned. +pub fn list(args:&Value)->Result { + let dir=storage(args)?; + let session=args.get("session_id").and_then(Value::as_str); + let principal=args.get("principal_ref").and_then(Value::as_str); + let mut items=Vec::new(); + let rd=fs::read_dir(&dir).map_err(|e|format!("workflow list: {e}"))?; + for ent in rd.flatten() { + let path=ent.path(); + if path.extension().and_then(|x|x.to_str())!=Some("json") { continue; } + if path.file_name().and_then(|x|x.to_str()) + .map(|x|x.starts_with('.')).unwrap_or(false) { continue; } + let Ok(text)=fs::read_to_string(&path) else { continue }; + let Ok(doc)=serde_json::from_str::(&text) else { continue }; + let meta=&doc["meta"]; + if meta["kind"].as_str()!=Some("MarqdoAgentFlowV1") { continue; } + if session.is_some() && meta["identity"]["session_id"].as_str()!=session { continue; } + if principal.is_some() && meta["identity"]["principal_ref"].as_str()!=principal { continue; } + let steps=meta["steps"].as_array().map(|x|x.len()).unwrap_or(0); + let completed=meta["completed"].as_array().map(|x|x.len()).unwrap_or(0); + items.push(json!({ + "id":doc.get("id").cloned().unwrap_or(Value::Null), + "status":doc.get("status").cloned().unwrap_or(Value::Null), + "cursor":meta.get("cursor").cloned().unwrap_or(Value::Null), + "total_steps":steps, + "completed_steps":completed, + "source_revision":meta["identity"]["source_revision"], + "updated_at":doc.get("updated_at").cloned().unwrap_or(Value::Null) + })); + } + items.sort_by(|a,b| a["id"].as_str().cmp(&b["id"].as_str())); + Ok(json!({"ok":true,"items":items,"resume_dir":dir.to_string_lossy()})) +} + /// Commit a verified result for the exact current step. All mutations are /// serialized with a lock; a completed step cannot be committed a second time. pub fn commit(args: &Value) -> Result { @@ -578,6 +643,29 @@ mod tests { assert_eq!(out["completed"][0]["value"]["items"][1]["result"]["value"]["value"],"fixed"); } + #[test] + fn inspect_and_list_are_read_only_and_session_scoped() { + let mut a=fixture(); + a["session_id"]=json!("s1"); + a["principal_ref"]=json!("u1"); + open(&a).unwrap(); + let seen=inspect(&a).unwrap(); + assert_eq!(seen["status"],"running"); + assert_eq!(seen["action"],"waiting_model"); + assert_eq!(seen["total_steps"],3); + assert_eq!(seen["completed_steps"],0); + assert_eq!(seen["step"]["id"],"choose"); + // Inspection must not consume the current step. + assert_eq!(next(&a).unwrap()["status"],"waiting_model"); + let listed=list(&a).unwrap(); + assert!(listed["items"].as_array().unwrap() + .iter().any(|x|x["id"]==a["id"])); + let mut other=a.clone(); + other["session_id"]=json!("s2"); + assert_eq!(inspect(&other).unwrap()["status"],"not_found_or_mismatched"); + assert!(list(&other).unwrap()["items"].as_array().unwrap().is_empty()); + } + #[test] fn explicit_cancel_stops_future_commits() { let a=fixture(); diff --git a/tests/ext/ai-native-workflow.mq.md b/tests/ext/ai-native-workflow.mq.md index 418f787..83d8ca0 100644 --- a/tests/ext/ai-native-workflow.mq.md +++ b/tests/ext/ai-native-workflow.mq.md @@ -5,51 +5,89 @@ import: workflow: ext/ai/workflow.mq.md json: lib/json.mq.md sys: lib/sys.mq.md + time: lib/time.mq.md --- # main Offline test: the same Marqdo program advances through model choice, user -input and terminal state with plugin-owned durable checkpoints. +input and terminal state with plugin-owned durable checkpoints. The run ID and +checkpoint directory include the current millisecond so repeated local runs +start clean instead of reopening yesterday's completed workflow. + +**now = > time.now_ms** +**stamp = > json.stringify value=`now`** +**rid = "abi_flow_ci_" + stamp** +**dir = ".marqdo/ai-native-workflow-" + stamp** **steps = > json.parse text=[{"id":"intent","kind":"model","prompt":"Choose next skill","options":["chat","office"]},{"id":"confirm","kind":"input","question":"Continue?","options":["yes","no"]},{"id":"end","kind":"return"}]** -**opened = > workflow.open id="abi_flow_ci_20261118" steps=`steps` source_revision="flow-v1"** +**opened = > workflow.open id=`rid` steps=`steps` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **o = > json.get value=`opened` key="ok"** 1. `o` **_ = 1** 2. * > sys.exit code=21 -**first = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** +**seen = > workflow.inspect id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** +**seen_status = > json.get value=`seen` key="action"** +**seen_total = > json.get value=`seen` key="total_steps"** +1. `seen_status` == "waiting_model" + 1. `seen_total` == 3 + **_ = 1** + 2. * + > sys.exit code=30 +2. * + > sys.exit code=31 + +**listed = > workflow.list session_id="ci-session" resume_dir=`dir`** +**listed_ok = > json.get value=`listed` key="ok"** +**listed_items = > json.get value=`listed` key="items"** +**listed_n = > len value=`listed_items`** +1. `listed_ok` + 1. `listed_n` > 0 + **_ = 1** + 2. * + > sys.exit code=32 +2. * + > sys.exit code=33 + +**first = > workflow.next id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **first_state = > json.get value=`first` key="status"** 1. `first_state` == "waiting_model" **_ = 1** 2. * > sys.exit code=22 -**c1 = > workflow.commit id="abi_flow_ci_20261118" step_id="intent" response="chat" source_revision="flow-v1"** +**c1 = > workflow.commit id=`rid` step_id="intent" response="chat" source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **done1 = > json.get value=`c1` key="ok"** 1. `done1` **_ = 1** 2. * > sys.exit code=23 -**second = > workflow.tick id="abi_flow_ci_20261118" source_revision="flow-v1"** +**progress = > workflow.inspect id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** +**progress_done = > json.get value=`progress` key="completed_steps"** +1. `progress_done` == 1 + **_ = 1** +2. * + > sys.exit code=34 + +**second = > workflow.tick id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **second_state = > json.get value=`second` key="status"** 1. `second_state` == "waiting_input" **_ = 1** 2. * > sys.exit code=24 -**c2 = > workflow.commit id="abi_flow_ci_20261118" step_id="confirm" response="yes" source_revision="flow-v1"** +**c2 = > workflow.commit id=`rid` step_id="confirm" response="yes" source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **done2 = > json.get value=`c2` key="ok"** 1. `done2` **_ = 1** 2. * > sys.exit code=25 -**c3 = > workflow.tick id="abi_flow_ci_20261118" source_revision="flow-v1"** -**complete = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** +**c3 = > workflow.tick id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** +**complete = > workflow.next id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **status = > json.get value=`complete` key="status"** 1. `status` == "succeeded" **_ = 1** @@ -57,10 +95,11 @@ input and terminal state with plugin-owned durable checkpoints. > sys.exit code=26 **partial_steps = > json.parse text=[{"id":"children","kind":"parallel","effect_class":"read","tasks":[{"path":"worker-a.mq.md"},{"path":"worker-b.mq.md"}]}]** -**new_batch = > workflow.open id="abi_flow_partial_ci_20261118" steps=`partial_steps` source_revision="flow-v1"** +**prid = "abi_flow_partial_ci_" + stamp** +**new_batch = > workflow.open id=`prid` steps=`partial_steps` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **parts = > json.parse text=[{"ok":true,"value":{"code":0,"value":"useful"}},{"ok":false,"error":"timeout"}]** -**stopped = > workflow.commit id="abi_flow_partial_ci_20261118" step_id="children" response=`parts` source_revision="flow-v1"** -**reloaded = > workflow.next id="abi_flow_partial_ci_20261118" source_revision="flow-v1"** +**stopped = > workflow.commit id=`prid` step_id="children" response=`parts` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** +**reloaded = > workflow.next id=`prid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **partial = > json.get value=`reloaded` key="partial"** **survivors = > json.get value=`partial` key="succeeded"** 1. `survivors` == 1 @@ -68,14 +107,14 @@ input and terminal state with plugin-owned durable checkpoints. 2. * > sys.exit code=27 -**retry_plan = > workflow.retry_plan id="abi_flow_partial_ci_20261118" source_revision="flow-v1"** +**retry_plan = > workflow.retry_plan id=`prid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **allowed = > json.get value=`retry_plan` key="ok"** 1. `allowed` **_ = 1** 2. * > sys.exit code=28 **repaired = > json.parse text=[{"ok":true,"value":{"code":0,"value":"repaired"}}]** -**merged = > workflow.retry_commit id="abi_flow_partial_ci_20261118" results=`repaired` source_revision="flow-v1"** +**merged = > workflow.retry_commit id=`prid` results=`repaired` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **merged_ok = > json.get value=`merged` key="ok"** 1. `merged_ok` **_ = 1**