From e1ff3fa9c05f9294dcb77d182218be92cc1ed2d6 Mon Sep 17 00:00:00 2001 From: sascha2101 Date: Mon, 26 Oct 2026 11:11:10 +0000 Subject: [PATCH] Batch: refuse a step that would fail at its turn before the first step runs (#5853) (#6781) * claim: #5853 * Batch: refuse a step that would fail at its turn before the first step runs (#5853) engine.batch and the MCP batch tool checked only a batch's shape up front. A misspelled command id in a late step was found at its turn, after every earlier step had run, and then all of it was rolled back: a 160-step batch with a typo as its last step ran for a minute and changed nothing. solidcraft_engine::batch_preflight::check finds, before anything runs, the first step the batch would certainly refuse at its turn: a step without a command, an unknown command id (the error names the closest ids, as at the step's turn) or, with strict parameter checking, a call that breaks its command's typed contract. Anything that depends on the design is left to the step's turn. - engine.batch (control channel) checks against the app's registry and its session's level; view.pick, which the app answers itself, passes. - The MCP batch tool checks when the commands run in its own process (headless, with --param-check from the backend). A running app may be another version with other commands and checks the batch itself; its reply's not_run is passed on. - The refusal is the failing step's reply with completed 0, undone 0, not_run listing every step and a note. Tests that used an unknown command only to make a late step fail now use a step that fails at its turn (a bad extrude distance), so they still test rollback, timings and file.new as before. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FN5eEMrqWWXqi65FcK8GXq --------- Co-authored-by: sascha2101 <221609842+sascha2101@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 --- crates/engine/src/batch_preflight.rs | 134 +++++++++++++++++++++++++++ crates/engine/src/lib.rs | 1 + crates/mcp/src/backend.rs | 14 +++ crates/mcp/src/tests.rs | 26 +++++- crates/mcp/src/tools.rs | 19 +++- crates/ui-egui/src/control.rs | 51 +++++++++- docs/control-protocol.md | 2 +- docs/mcp.md | 2 +- 8 files changed, 239 insertions(+), 10 deletions(-) create mode 100644 crates/engine/src/batch_preflight.rs diff --git a/crates/engine/src/batch_preflight.rs b/crates/engine/src/batch_preflight.rs new file mode 100644 index 000000000..b3b8802ad --- /dev/null +++ b/crates/engine/src/batch_preflight.rs @@ -0,0 +1,134 @@ +//! A batch's steps checked before the first one runs (#5853). +//! +//! A batch runner (the control channel's `engine.batch`, the MCP `batch` tool) runs its steps in +//! order and stops at the first failure, going back to the design as it was. A misspelled +//! command id in a late step was found only at its turn, after every earlier step had run, and +//! then all of that work was undone: a 160-step batch with a typo as its last step ran for a +//! minute and changed nothing. [`check`] finds, before anything runs, the first step the batch +//! would certainly refuse at its turn, so the runner can refuse the batch unrun: +//! +//! - a step without a command id; +//! - a command id no command has (the error names the closest ids, as at the step's turn); +//! - with the session's [`ParamCheck::Strict`], parameters that break the command's typed +//! contract (the contract check is the one the step would get; it reads only the parameters). +//! +//! Anything that depends on the design (a face that isn't there yet, an expression naming a +//! parameter an earlier step makes) is left to the step's turn, as are parameters that strict +//! checking would not refuse. + +use serde_json::{Value, json}; + +use crate::schema::ParamCheck; +use crate::{EngineError, find_command}; + +/// The first step a batch would refuse at its turn. +#[derive(Clone, Debug, PartialEq)] +pub struct Refusal { + pub index: usize, + pub command: Option, + pub error: String, +} + +impl Refusal { + /// The batch reply for a batch refused before its first step: as a failed step's reply, + /// with nothing completed, nothing undone and every step not run. + pub fn reply(&self, steps: usize) -> Value { + json!({ + "completed": 0, + "results": [], + "failed": {"index": self.index, "command": self.command, "error": self.error}, + "undone": 0, + "rolled_back": false, + "not_run": (0..steps).collect::>(), + "note": "nothing was run: the batch was checked before its first step", + }) + } +} + +/// The first of `steps` (`{command | id, params?}`) that would be refused at its turn whatever +/// the steps before it do, checked against the command registry and, at `level` +/// [`ParamCheck::Strict`], the commands' typed contracts. `host` names ids the runner answers +/// itself, outside the registry (the app's `view.pick`). +pub fn check(steps: &[Value], level: ParamCheck, host: &[&str]) -> Option { + for (index, step) in steps.iter().enumerate() { + let Some(id) = step.get("command").or_else(|| step.get("id")).and_then(Value::as_str) else { + return Some(Refusal { index, command: None, error: "missing `command`".into() }); + }; + if host.contains(&id) { + continue; + } + let Some(spec) = find_command(id) else { + return Some(Refusal { index, command: Some(id.to_string()), error: EngineError::UnknownCommand(id.to_string()).to_string() }); + }; + if level == ParamCheck::Strict + && let Some(contract) = spec.contract + && let Some(first) = contract.check(step.get("params").unwrap_or(&Value::Null)).into_iter().next() + { + return Some(Refusal { index, command: Some(id.to_string()), error: crate::params::bad(id, first.message).to_string() }); + } + } + None +} + +#[cfg(test)] +mod tests { + use super::*; + + fn step(command: &str, params: Value) -> Value { + json!({"command": command, "params": params}) + } + + /// 40 circles extruded, as in the issue: 160 good steps. + fn circles() -> Vec { + (0..40) + .flat_map(|k| { + [ + step("sketch.create", json!({"plane": "XY"})), + step("sketch.circle.center", json!({"center": [k * 7, (k % 5) * 3], "radius": 5})), + json!({"command": "sketch.finish"}), + step("solid.extrude", json!({"distance": 20 + k, "operation": "new"})), + ] + }) + .collect() + } + + #[test] + fn a_typo_in_the_last_step_is_found_before_the_first_runs() { + let mut steps = circles(); + assert_eq!(check(&steps, ParamCheck::Off, &[]), None, "every step names a command"); + steps.push(step("solid.extrud", json!({"distance": 5}))); + let r = check(&steps, ParamCheck::Off, &[]).unwrap(); + assert_eq!((r.index, r.command.as_deref()), (160, Some("solid.extrud"))); + assert!(r.error.starts_with("unknown command `solid.extrud`") && r.error.contains("solid.extrude"), "{}", r.error); + let reply = r.reply(steps.len()); + assert_eq!((reply["completed"].clone(), reply["undone"].clone(), reply["rolled_back"].clone()), (json!(0), json!(0), json!(false))); + assert_eq!(reply["not_run"].as_array().map(Vec::len), Some(161), "nothing ran"); + assert_eq!(reply["failed"]["index"], 160); + } + + #[test] + fn a_step_without_a_command_and_the_first_bad_step_are_named() { + let steps = vec![step("solid.box", json!({"length": 1, "width": 1, "height": 1})), json!({"params": {}}), step("nope.nope", json!({}))]; + assert_eq!(check(&steps, ParamCheck::Off, &[]), Some(Refusal { index: 1, command: None, error: "missing `command`".into() })); + // `id` is read as `command` is, and an id the runner answers itself passes. + let steps = vec![json!({"id": "solid.box", "params": {"length": 1, "width": 1, "height": 1}}), step("view.pick", json!({"x": 1, "y": 1}))]; + assert_eq!(check(&steps, ParamCheck::Off, &["view.pick"]), None); + assert_eq!(check(&steps, ParamCheck::Off, &[]).map(|r| r.index), Some(1), "outside the registry without the runner"); + } + + #[test] + fn strict_checking_refuses_a_broken_contract_before_the_first_step() { + let steps = + vec![step("solid.box", json!({"length": 1, "width": 1, "height": 1})), step("solid.box", json!({"lenght": 1, "width": 1, "height": 1}))]; + // Off and warn run such a step (warn reports it): nothing to refuse up front. + assert_eq!(check(&steps, ParamCheck::Off, &[]), None); + assert_eq!(check(&steps, ParamCheck::Warn, &[]), None); + let r = check(&steps, ParamCheck::Strict, &[]).unwrap(); + assert_eq!(r.index, 1); + assert!(r.error.contains("solid.box") && r.error.contains("lenght"), "{}", r.error); + // The same call alone is refused with the same words at its turn. + let mut s = crate::Session { param_check: ParamCheck::Strict, ..crate::Session::default() }; + let at_turn = s.execute("solid.box", &steps[1]["params"]).unwrap_err().to_string(); + assert_eq!(r.error, at_turn); + } +} diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs index a65f9829d..70bc1c8f2 100644 --- a/crates/engine/src/lib.rs +++ b/crates/engine/src/lib.rs @@ -9,6 +9,7 @@ pub mod agent_setup; pub mod batch_params; +pub mod batch_preflight; pub mod capture; pub mod cmd; pub mod control_auth; diff --git a/crates/mcp/src/backend.rs b/crates/mcp/src/backend.rs index f6b30ef4d..023ba44f5 100644 --- a/crates/mcp/src/backend.rs +++ b/crates/mcp/src/backend.rs @@ -33,6 +33,11 @@ pub trait Backend { fn notice(&self) -> Option { None } + /// How this side's session checks commands' typed contracts (`--param-check`), when this + /// process holds it. A running app checks its own (`engine.batch`), so `Remote` says off. + fn param_check(&self) -> solidcraft_engine::schema::ParamCheck { + solidcraft_engine::schema::ParamCheck::Off + } } /// Longest reply line accepted from the app. @@ -567,6 +572,9 @@ impl Backend for Headless { fn in_process(&self) -> bool { true } + fn param_check(&self) -> solidcraft_engine::schema::ParamCheck { + self.session.param_check + } } /// `solidcraft-cli mcp` with no `--connect`: a headless session while no app runs, which gives @@ -630,6 +638,12 @@ impl Backend for Auto { fn in_process(&self) -> bool { self.remote.is_none() } + fn param_check(&self) -> solidcraft_engine::schema::ParamCheck { + match (&self.remote, &self.headless) { + (None, Some(h)) => h.param_check(), + _ => solidcraft_engine::schema::ParamCheck::Off, + } + } fn notice(&self) -> Option { self.headless.as_ref().map(|_| { "Note: this is a headless session because the SolidCraft app was not found; the user cannot see this work. \ diff --git a/crates/mcp/src/tests.rs b/crates/mcp/src/tests.rs index bedd14d1f..bde44a912 100644 --- a/crates/mcp/src/tests.rs +++ b/crates/mcp/src/tests.rs @@ -490,13 +490,30 @@ fn batch_stops_at_first_error_and_rolls_back() { let r = raw_tool( &mut s, "batch", - json!({"rollback": false, "commands": [{"command": "solid.sphere", "params": {"radius": 3, "center": [50, 0, 0]}}, {"command": "NoSuchCommand"}]}), + json!({"rollback": false, "commands": [{"command": "solid.sphere", "params": {"radius": 3, "center": [50, 0, 0]}}, {"command": "solid.extrude", "params": {"distance": "bogus +"}}]}), ); assert_eq!(r["result"]["isError"], true); - assert!(r["result"]["content"][0]["text"].as_str().unwrap().contains("NoSuchCommand")); + assert!(r["result"]["content"][0]["text"].as_str().unwrap().contains("solid.extrude")); assert_eq!(tool(&mut s, "measure", json!({}))["body_count"], 2); } +/// #5853: a misspelled command, however late in the batch, refuses the batch before its first +/// step: nothing runs, nothing is undone, and the error names the closest command. +#[test] +fn batch_refuses_an_unknown_command_before_the_first_step() { + let mut s = server(); + let mut steps: Vec = (0..20).map(|k| json!({"command": "solid.sphere", "params": {"radius": 1, "center": [k * 5, 0, 0]}})).collect(); + steps.push(json!({"command": "solid.extrud", "params": {"distance": 5}})); + let r = raw_tool(&mut s, "batch", json!({"commands": steps})); + assert_eq!(r["result"]["isError"], true, "{r}"); + let body: Value = serde_json::from_str(r["result"]["content"][0]["text"].as_str().unwrap()).unwrap(); + assert_eq!((body["completed"].clone(), body["failed"]["index"].clone(), body["undone"].clone()), (json!(0), json!(20), json!(0)), "{body}"); + assert!(body["failed"]["error"].as_str().is_some_and(|e| e.contains("closest: `solid.extrude`")), "{body}"); + assert_eq!((body["applied"].clone(), body["not_run"].as_array().map(Vec::len)), (json!([]), Some(21)), "{body}"); + assert_eq!(tool(&mut s, "measure", json!({}))["body_count"], 0, "no step ran"); + assert_eq!(tool(&mut s, "inspect_design", json!({"measure": false}))["undo"], 0); +} + /// #5822: with `coalesce_parameters` a batch of parameter edits, one per step, rebuilds the /// design once for the run, and every step still has its own result. A run with an edit /// `changes` can't make (a new parameter) goes step by step, and a refused edit is still named @@ -607,7 +624,8 @@ fn a_failed_batch_with_file_new_restores_the_original_design() { json!({"rollback": true, "commands": [ {"command": "file.new", "params": {"name": "Replacement"}}, {"command": "solid.box", "params": {"length": 2, "width": 2, "height": 2}}, - {"command": "not.a.command"}, + // Fails at its turn (an unknown command would be refused before the first step, #5853). + {"command": "solid.extrude", "params": {"distance": "bogus +"}}, ]}), ); assert_eq!(r["result"]["isError"], true, "{r}"); @@ -1826,7 +1844,7 @@ fn batch_reports_timings_and_profile() { let r = raw_tool( &mut s, "batch", - json!({"timings": true, "commands": [{"command": "solid.box", "params": {"length": 1, "width": 1, "height": 1}}, {"command": "NoSuchCommand"}]}), + json!({"timings": true, "commands": [{"command": "solid.box", "params": {"length": 1, "width": 1, "height": 1}}, {"command": "solid.extrude", "params": {"distance": "bogus +"}}]}), ); let body: Value = serde_json::from_str(r["result"]["content"][0]["text"].as_str().unwrap()).unwrap(); assert_eq!(body["timings"].as_array().map(Vec::len), Some(2), "the failing step is timed too: {body}"); diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rs index 6f0660a48..dbf3ce6ef 100644 --- a/crates/mcp/src/tools.rs +++ b/crates/mcp/src/tools.rs @@ -790,6 +790,22 @@ fn batch(b: &mut dyn Backend, a: &Map) -> Value { } } let steps = &mapped; + // A step the batch would refuse at its turn refuses it now, before anything runs (#5853). + // Only where the commands run in this process: a running app may be another version, with + // commands this one lacks, and checks the batch against its own registry when it gets it. + if b.in_process() + && let Some(refusal) = solidcraft_engine::batch_preflight::check(steps, b.param_check(), &[]) + { + let mut reply = refusal.reply(steps.len()); + if let Some(o) = reply.as_object_mut() { + o.insert("ok".into(), Value::Bool(false)); + o.insert("applied".into(), json!([])); + } + if let (Some(command), Some(failed)) = (refusal.command.as_deref(), reply.get_mut("failed").and_then(Value::as_object_mut)) { + failed.insert("error".into(), Value::String(command_error(command, refusal.error.clone()))); + } + return text_result(&reply, true); + } // A `list_commands` step's catalog, filtered as the tool filters it. let narrow = |i: usize, v: Value| match filters.iter().find(|(j, _)| *j == i) { Some((_, f)) => filter_commands(v, Some(f)), @@ -948,7 +964,8 @@ fn batch_reply(r: &Value, len: usize, rollback: bool, verbose: bool, narrow: &dy "rolled_back": rolled_back, "undone": r["undone"], "applied": applied, - "not_run": (completed + 1..len).collect::>(), + // An app that refused the batch before its first step says what didn't run. + "not_run": r.get("not_run").filter(|v| v.is_array()).cloned().unwrap_or_else(|| json!((completed + 1..len).collect::>())), "results": results, }), true, diff --git a/crates/ui-egui/src/control.rs b/crates/ui-egui/src/control.rs index 5eca34b60..84d5f9542 100644 --- a/crates/ui-egui/src/control.rs +++ b/crates/ui-egui/src/control.rs @@ -287,6 +287,10 @@ fn batch(app: &mut SolveApp, p: &Value) -> Outcome { if let Some(why) = batch_refusal(steps) { return err(why); } + // A step the batch would refuse at its turn refuses it now, before anything runs (#5853). + if let Some(refusal) = solidcraft_engine::batch_preflight::check(steps, app.session.param_check, &["view.pick"]) { + return ok(refusal.reply(steps.len())); + } let rollback = p.get("rollback").and_then(Value::as_bool).unwrap_or(true); let profile = p.get("profile").and_then(Value::as_bool).unwrap_or(false); let timed = profile || p.get("timings").and_then(Value::as_bool).unwrap_or(false); @@ -1577,7 +1581,8 @@ mod tests { assert_eq!(rows[1]["index"], 1); assert!(rows[1]["profile"]["boolean_ms"].as_f64().is_some_and(|ms| ms > 0.0), "{v}"); assert!(v["result"]["total_ms"].as_f64().is_some(), "{v}"); - let v = batch(&mut h, json!({"timings": true, "commands": [{"command": "NoSuchCommand"}]})); + // A step that fails at its turn is timed too. + let v = batch(&mut h, json!({"timings": true, "commands": [{"command": "solid.extrude", "params": {"distance": "bogus +"}}]})); assert_eq!(v["result"]["timings"].as_array().map(Vec::len), Some(1), "{v}"); assert!(v["result"]["timings"][0].get("profile").is_none(), "{v}"); let v = batch(&mut h, json!({"commands": [{"command": "solid.box", "params": {"length": 1, "width": 1, "height": 1}}]})); @@ -1614,7 +1619,8 @@ mod tests { &mut h, json!({"rollback": false, "commands": [ {"command": "solid.sphere", "params": {"radius": 3}}, - {"command": "NoSuchCommand"}, + // Fails at its turn (an unknown command would be refused before the first step, #5853). + {"command": "solid.extrude", "params": {"distance": "bogus +"}}, ]}), ); assert_eq!(v["result"]["failed"]["index"], 1, "{v}"); @@ -1630,6 +1636,45 @@ mod tests { assert!(v["result"]["failed"]["error"].as_str().is_some_and(|e| e.contains("missing `command`")), "{v}"); } + /// #5853: a step the batch would refuse at its turn (an unknown command; with strict + /// parameter checking, a call that breaks its command's contract) refuses the batch before + /// its first step runs, however late the step is. + #[test] + fn engine_batch_refuses_a_bad_step_before_the_first_runs() { + let mut h = crate::scenario::Harness::new(); + let before = inspect(&mut h); + let v = batch( + &mut h, + json!({"commands": [ + {"command": "solid.box", "params": {"length": 10, "width": 10, "height": 10}}, + {"command": "solid.sphere", "params": {"radius": 3, "center": [50, 0, 0]}}, + {"command": "solid.extrud", "params": {"distance": 5}}, + ]}), + ); + assert_eq!(v["ok"], true, "{v}"); + let r = &v["result"]; + assert_eq!((r["completed"].clone(), r["failed"]["index"].clone(), r["undone"].clone()), (json!(0), json!(2), json!(0)), "{v}"); + assert!(r["failed"]["error"].as_str().is_some_and(|e| e.starts_with("unknown command `solid.extrud`") && e.contains("solid.extrude")), "{v}"); + assert_eq!(r["not_run"], json!([0, 1, 2]), "{v}"); + let after = inspect(&mut h); + assert_eq!((after["bodies"].clone(), after["undo"].clone()), (before["bodies"].clone(), before["undo"].clone()), "nothing ran: {after}"); + // Strict checking refuses a broken contract up front too; off, the step runs (and the + // box command reads what it knows). + h.app.session.param_check = solidcraft_engine::schema::ParamCheck::Strict; + let steps = json!([ + {"command": "solid.sphere", "params": {"radius": 3}}, + {"command": "solid.box", "params": {"lenght": 10, "width": 10, "height": 10}}, + ]); + let v = batch(&mut h, json!({"commands": steps})); + assert_eq!((v["result"]["completed"].clone(), v["result"]["failed"]["index"].clone()), (json!(0), json!(1)), "{v}"); + assert!(v["result"]["failed"]["error"].as_str().is_some_and(|e| e.contains("lenght")), "{v}"); + assert_eq!(inspect(&mut h)["bodies"], before["bodies"], "nothing ran"); + // `view.pick` is answered by the app, outside the command registry: not refused. + h.app.session.param_check = solidcraft_engine::schema::ParamCheck::Off; + let v = batch(&mut h, json!({"commands": [{"command": "view.pick", "params": {"x": 1, "y": 1}}]})); + assert!(!v["result"]["failed"]["error"].as_str().is_some_and(|e| e.starts_with("unknown command")), "{v}"); + } + #[test] fn engine_batch_is_refused_when_a_step_loads_a_file() { let mut h = crate::scenario::Harness::new(); @@ -1660,7 +1705,7 @@ mod tests { #[test] fn engine_batch_reports_whether_it_rolled_back() { let mut h = crate::scenario::Harness::new(); - let steps = json!([{"command": "solid.box", "params": {"length": 10, "width": 10, "height": 10}}, {"command": "NoSuchCommand"}]); + let steps = json!([{"command": "solid.box", "params": {"length": 10, "width": 10, "height": 10}}, {"command": "solid.extrude", "params": {"distance": "bogus +"}}]); let v = batch(&mut h, json!({"commands": steps.clone()})); assert_eq!((&v["result"]["rolled_back"], &v["result"]["undone"]), (&json!(true), &json!(1)), "{v}"); let v = batch(&mut h, json!({"commands": steps, "rollback": false})); diff --git a/docs/control-protocol.md b/docs/control-protocol.md index ef103931e..ba47e87ce 100644 --- a/docs/control-protocol.md +++ b/docs/control-protocol.md @@ -134,7 +134,7 @@ MCP server sends its folders this way on every request ([mcp.md](mcp.md)). Witho |---|---|---| | `engine.execute` | `command`: command id, `params`: JSON object | the command's result | | `engine.script` | `commands`: `[{command, params}, …]` | results, stops at the first error | -| `engine.batch` | `commands`: `[{command, params}, …]` (at most 10 000), `rollback?`: bool (default true), `timings?`, `profile?`, `coalesce_parameters?`: bool (default false) | `{completed, results, undone}`, plus `failed: {index, command, error}` when a step fails, and with `timings` `timings: [{index, command, ms}]` (the failing step included) and `total_ms`; `profile` adds each step's `profile: {boolean_ms, tessellate_ms, other_ms}`. Runs the steps in one request, so within one frame, each as `engine.execute` runs it. The first failure stops the batch, and with `rollback` the design goes back to how it was before it (`undone`: the steps taken back, `rolled_back`: whether the design is back as it was, `false` only when the checkpoint could not restore it). Refused before anything runs, with an error starting `engine.batch unavailable`, while the agent cursor is shown or when a step loads a file (`doc.open`, `file.insert_step`, `file.insert_mesh`). Send such steps one by one. With `coalesce_parameters`, each run of consecutive plain parameter edits (`parameters.change` with only a name and an expression, or with `changes`) is set as one `parameters.change {changes}`, so the design rebuilds once for the run. Every step still gets its own result (with `coalesced`: the run's length), and the run is one undo step. The run skips the states between its edits: an edit that would be refused on its own, but not once the run's later edits are in, goes through. A run whose combined edit is refused (a new parameter, a bad expression) runs step by step, so the refused step is named. Answered when done, for up to 3600 s | +| `engine.batch` | `commands`: `[{command, params}, …]` (at most 10 000), `rollback?`: bool (default true), `timings?`, `profile?`, `coalesce_parameters?`: bool (default false) | `{completed, results, undone}`, plus `failed: {index, command, error}` when a step fails, and with `timings` `timings: [{index, command, ms}]` (the failing step included) and `total_ms`; `profile` adds each step's `profile: {boolean_ms, tessellate_ms, other_ms}`. Runs the steps in one request, so within one frame, each as `engine.execute` runs it. The first failure stops the batch, and with `rollback` the design goes back to how it was before it (`undone`: the steps taken back, `rolled_back`: whether the design is back as it was, `false` only when the checkpoint could not restore it). Refused before anything runs, with an error starting `engine.batch unavailable`, while the agent cursor is shown or when a step loads a file (`doc.open`, `file.insert_step`, `file.insert_mesh`). Send such steps one by one. A step the batch would certainly refuse at its turn is found before the first step runs (#5853): a step without a command, an unknown command id (with the closest ids) or, with strict parameter checking, a call that breaks its command's contract. The reply is then that step's failure with `completed: 0`, `undone: 0`, `not_run` listing every step and a `note`; nothing has run. With `coalesce_parameters`, each run of consecutive plain parameter edits (`parameters.change` with only a name and an expression, or with `changes`) is set as one `parameters.change {changes}`, so the design rebuilds once for the run. Every step still gets its own result (with `coalesced`: the run's length), and the run is one undo step. The run skips the states between its edits: an edit that would be refused on its own, but not once the run's later edits are in, goes through. A run whose combined edit is refused (a new parameter, a bad expression) runs step by step, so the refused step is named. Answered when done, for up to 3600 s | | `engine.commands` | — | every command: id, label, tab, panel, icon, shortcut, params doc, enabled | | `document.revision` | — | `{document_id, revision}`: the active design's id and a number that moves whenever the design changes, for programs that follow it ([Following the design](#following-the-design)) | | `control.subscribe` | — | `{document_id, revision}`, as `document.revision`; the connection is then sent a `design.changed` line whenever they change ([Following the design](#following-the-design)) | diff --git a/docs/mcp.md b/docs/mcp.md index 1b2c124c2..d7e50c2c3 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -261,7 +261,7 @@ The `skill_reference` tool returns these documents from the copies built into So | `list_commands` | `filter?` | The command catalog: id, label, tab/panel, shortcut, parameter docs, enabled now. `filter` matches id, label, tab and panel. | | `describe_command` | `id` | One command's parameter docs (`params`) and, for commands with a typed contract (every new command, and more of the older ones as they are converted), the JSON Schemas (2020-12) of its parameters (`input`) and of a successful result (`output`); `null` for the others. The same as `execute` `engine.describe {command}`. | | `execute` | `command`, `params?`, `verbose?` (default true) | Run any command with JSON parameters (`list_commands` shows them). Failures leave the design unchanged. A feature command replies with the feature (`feature`, `name`), every body (`bodies`) and the bodies it created, changed and removed (`created_bodies`, `changed_bodies`, `removed_bodies`). `verbose: false` uses the same compact reply as `batch`. | -| `batch` | `commands: [{command, params}]`, `rollback?` (default true), `verbose?` (default true), `timings?`, `profile?`, `coalesce_parameters?` (default false) | Run steps in order, stop at the first error and undo the completed steps. The reply names the failing step (`failed.index`, `failed.command`, `failed.error`), every result before it, `rolled_back` (true only when the design really went back to where the batch started), `undone`, `applied` (the indices of the steps whose changes are in the design) and `not_run` (the steps never sent). A step may name a tool instead of a command, with that tool's arguments as `params`: `set_parameter` (runs `parameters.change`; `value` or `expression`), `list_commands` (`engine.commands`, filtered by `filter` as the tool filters it), `describe_command` (`engine.describe`), `execute` (`{command, params}`), `measure`, `inspect_design` (`document.inspect`: each sketch as its counts, not its full contents, and no joints), `undo`, `redo`, `export`, `save`, `open`, `new_design` and `crash_reports`. `screenshot`, `body_topology` (use `model.edges` and `model.faces`), `batch`, `pending`, `running` and `skill_reference` can't be steps: such a batch fails before anything is sent. `verbose: false` keeps the reply small in large designs: feature steps leave out the full body list (`created_bodies`, `changed_bodies`, `removed_bodies` stay) and sketch steps the ids they repeat outside `created`. Bridged to an app that has `engine.batch`, the whole batch is one control request (one frame of the app). Older apps, and apps showing the agent cursor, get the steps one by one. `timings: true` adds `timings: [{index, command, ms}]` for every step run, the failing one included, and `total_ms`. `profile: true` also adds each step's `profile: {boolean_ms, tessellate_ms, other_ms}`, its time in kernel booleans, in tessellation and the rest. Steps are timed where they run: in the app when bridged. An app without `engine.batch` is timed step by step, without `profile`. `coalesce_parameters: true` sets each run of consecutive plain parameter edits (`parameters.change` or `set_parameter` with a name and a value, or `changes`) together, so the design rebuilds once per run instead of once per edit. Steps between runs see the design up to date. Each step keeps its own result (`coalesced`: the run's length), and the run is one undo step. The run skips the states between its edits, so an edit refused on its own can go through with the run's later ones. A refused run goes step by step, naming the refused step. | +| `batch` | `commands: [{command, params}]`, `rollback?` (default true), `verbose?` (default true), `timings?`, `profile?`, `coalesce_parameters?` (default false) | Run steps in order, stop at the first error and undo the completed steps. The reply names the failing step (`failed.index`, `failed.command`, `failed.error`), every result before it, `rolled_back` (true only when the design really went back to where the batch started), `undone`, `applied` (the indices of the steps whose changes are in the design) and `not_run` (the steps never sent). A step may name a tool instead of a command, with that tool's arguments as `params`: `set_parameter` (runs `parameters.change`; `value` or `expression`), `list_commands` (`engine.commands`, filtered by `filter` as the tool filters it), `describe_command` (`engine.describe`), `execute` (`{command, params}`), `measure`, `inspect_design` (`document.inspect`: each sketch as its counts, not its full contents, and no joints), `undo`, `redo`, `export`, `save`, `open`, `new_design` and `crash_reports`. `screenshot`, `body_topology` (use `model.edges` and `model.faces`), `batch`, `pending`, `running` and `skill_reference` can't be steps: such a batch fails before anything is sent. So does a step the batch would certainly refuse at its turn (#5853): a step without a command, an unknown command id (the error names the closest ids) or, with `--param-check strict`, parameters that break a command's contract. A headless session checks this itself; an app checks it against its own commands when it gets the batch. `verbose: false` keeps the reply small in large designs: feature steps leave out the full body list (`created_bodies`, `changed_bodies`, `removed_bodies` stay) and sketch steps the ids they repeat outside `created`. Bridged to an app that has `engine.batch`, the whole batch is one control request (one frame of the app). Older apps, and apps showing the agent cursor, get the steps one by one. `timings: true` adds `timings: [{index, command, ms}]` for every step run, the failing one included, and `total_ms`. `profile: true` also adds each step's `profile: {boolean_ms, tessellate_ms, other_ms}`, its time in kernel booleans, in tessellation and the rest. Steps are timed where they run: in the app when bridged. An app without `engine.batch` is timed step by step, without `profile`. `coalesce_parameters: true` sets each run of consecutive plain parameter edits (`parameters.change` or `set_parameter` with a name and a value, or `changes`) together, so the design rebuilds once per run instead of once per edit. Steps between runs see the design up to date. Each step keeps its own result (`coalesced`: the run's length), and the run is one undo step. The run skips the states between its edits, so an edit refused on its own can go through with the run's later ones. A refused run goes step by step, naming the refused step. | | `inspect_design` | `measure?` (default true), `sketches?` (default true), `joints?` (default true) | Design properties (`metadata`: project, author… and other tools' keys; set them with `execute` `document.metadata.set`), parameters, timeline (type, suppressed, rolled back, error, warning, timing), bodies (volume, area, centre of mass, bbox, face/edge/vertex counts, visible; `removed_later: true` while a sketch is being edited on a rolled-back timeline and a later feature deletes the body, which is then not shown), sketches (curves, points, constraints, profiles, DOF, solve status, visible), joints when the design has any (as `joint.inspect` gives them: each origin's occurrence, component and path, the snap as saved, the feature, face, edge or sketch curve (`sketch: {id, name, curve}`) its persistent names refer to, `resolves` and the `error` when it is lost; kind, offset, angle, flip, values, limits, expressions, motion links; `execute` `joint.inspect {joint}` gives one joint), selection, undo depth. Hide helper sketches, bodies or construction planes with `execute` `browser.visibility` (`{items, visible}` or `{folder, visible}`), and joint glyphs with `{joints: [id or name], visible}` or `{folder: "joints", visible}` (a hidden joint still constrains and drives; `joint.list` reports each joint's `visible`). | | `measure` | `body?` or `items?` | Area (mm²), bbox, topology counts and `closed` per body. Volume (mm³), volume centre of mass, density and mass are reported only for closed, consistently oriented bodies (null or omitted for open surfaces). Volume/mass totals skip open bodies; `total.open_bodies_skipped` gives their count. Area and topology totals include all bodies. With `items` (one or two selections as `execute` takes them: `face`, `edge`, `vertex`, `sketch_curve`, `profile`), the picked geometry instead: faces and edges need only `type`, `body` and `point`; `index` is optional. See below. | | `body_topology` | `body` | Edges (index, midpoint, length, ends) and faces (index, name, area, centroid, normal, `point`, and for a cylindrical face its `cylinder`: `origin`, `axis`, `radius`). An edge midpoint is the `[x,y,z]` that picks that edge for fillet and chamfer. A face's `point` lies on it and picks it (its centroid may not: that of a face with a hole is in the hole); a face's `name` picks it for the commands that take faces (`face.delete`, `solid.shell`, `solid.draft`, `solid.offset_face`, `solid.split_face`, `solid.replace_face`, and `face` of `sheet.convert`). |