diff --git a/crates/mcp/src/tests.rs b/crates/mcp/src/tests.rs index 859fc3c98..ef16301ff 100644 --- a/crates/mcp/src/tests.rs +++ b/crates/mcp/src/tests.rs @@ -954,6 +954,213 @@ fn a_failed_batch_with_file_new_restores_the_original_design() { assert_eq!(d["name"], name, "{d}"); } +/// `expect` on a batch: the volume, body count and bounding box the agent computed beforehand +/// are measured and compared by the server once the batch went through, so no separate +/// `measure` call and no comparison by hand follow every stage. +#[test] +fn a_batch_with_a_matching_expect_reports_the_expectation_met() { + let mut s = server(); + let r = tool( + &mut s, + "batch", + json!({ + "commands": [ + {"command": "solid.box", "params": {"length": 40, "width": 30, "height": 20, "corner": [0, 0, 0]}}, + {"command": "solid.box", "params": {"length": 10, "width": 10, "height": 10, "corner": [15, 10, 5], "operation": "cut"}}, + ], + "expect": {"volume_mm3": 23000, "bodies": 1, "bbox": {"min": [0, 0, 0], "max": [40, 30, 20]}}, + }), + ); + assert_eq!(r["completed"], 2, "{r}"); + let e = &r["expectation"]; + assert_eq!(e["ok"], true, "{r}"); + assert_eq!(e["mismatch"], json!([]), "{r}"); + assert_eq!(e["measured"]["bodies"], 1, "{r}"); + assert!(rel(e["measured"]["volume_mm3"].as_f64().unwrap(), 23000.0) < 1e-6, "{r}"); + assert!(rel(e["measured"]["bbox"]["max"][0].as_f64().unwrap(), 40.0) < 1e-6, "{r}"); + assert_eq!( + e["expected"], + json!({"volume_mm3": 23000.0, "tol": 0.002, "bodies": 1, "bbox": {"min": [0.0, 0.0, 0.0], "max": [40.0, 30.0, 20.0]}}), + "{r}" + ); + // Without `expect` the reply is as before. + tool(&mut s, "new_design", json!({})); + let box40 = json!({"command": "solid.box", "params": {"length": 40, "width": 30, "height": 20, "corner": [0, 0, 0]}}); + let r = tool(&mut s, "batch", json!({"commands": [box40]})); + assert!(r.get("expectation").is_none(), "{r}"); + // `expect` is the tool's argument, not a step key: a step carrying one runs as any step with + // a stray key does, and nothing is checked. + let sphere = json!({"command": "solid.sphere", "params": {"radius": 5, "center": [100, 0, 0]}, "expect": {"bodies": 7}}); + let r = tool(&mut s, "batch", json!({"commands": [sphere]})); + assert_eq!(r["completed"], 1, "{r}"); + assert!(r.get("expectation").is_none() && r["results"][0].get("expectation").is_none(), "{r}"); +} + +/// A volume the design does not match flags the reply as an error that names the mismatch +/// first, and keeps the design as built: the agent decides what to do with it. +#[test] +fn a_batch_with_a_wrong_expected_volume_is_flagged_and_the_design_kept() { + let mut s = server(); + let box40 = json!({"command": "solid.box", "params": {"length": 40, "width": 30, "height": 20, "corner": [0, 0, 0]}}); + let r = raw_tool(&mut s, "batch", json!({"commands": [box40], "expect": {"volume_mm3": 20000}})); + assert_eq!(r["result"]["isError"], true, "{r}"); + let content = r["result"]["content"].as_array().unwrap(); + let first = content[0]["text"].as_str().unwrap(); + assert!(first.starts_with("expectation not met: volume: measured 24000, expected 20000 (+20.00 %)."), "{first}"); + assert!(first.contains("kept as built"), "{first}"); + let body: Value = serde_json::from_str(content[1]["text"].as_str().unwrap()).unwrap(); + assert_eq!(body["ok"], true, "the batch itself went through: {body}"); + assert_eq!(body["completed"], 1, "{body}"); + assert_eq!(body["results"][0]["created_bodies"], json!(["Body1"]), "{body}"); + assert_eq!(body["expectation"]["ok"], false, "{body}"); + assert_eq!(body["expectation"]["mismatch"], json!(["volume: measured 24000, expected 20000 (+20.00 %)"]), "{body}"); + assert_eq!(body["expectation"]["expected"], json!({"volume_mm3": 20000.0, "tol": 0.002}), "{body}"); + // The design is kept as built, undoably. + assert_eq!(tool(&mut s, "measure", json!({}))["body_count"], 1); + assert!(rel(volume(&mut s), 24000.0) < 1e-9); + assert_eq!(tool(&mut s, "inspect_design", json!({"measure": false}))["undo"], 1); + // `tol` is relative to the expected volume: 0.5 % off passes at 1 %, not at the default 0.2 %. + let cube = json!({"command": "solid.box", "params": {"length": 10, "width": 10, "height": 10, "corner": [100, 0, 0]}}); + let r = tool(&mut s, "batch", json!({"commands": [cube], "expect": {"volume_mm3": 25000.0 * 1.005, "tol": 0.01}})); + assert_eq!(r["expectation"]["ok"], true, "{r}"); + let r = raw_tool(&mut s, "batch", json!({"commands": [{"command": "undo"}], "expect": {"volume_mm3": 24000.0 * 1.005}})); + assert_eq!(r["result"]["isError"], true, "{r}"); + assert!(r["result"]["content"][0]["text"].as_str().unwrap().contains("volume: measured 24000, expected 24120 (-0.50 %)"), "{r}"); +} + +/// A wrong body count and a wrong bounding box are each named, with the coordinates that are +/// off; a bounding box within 0.05 mm matches. +#[test] +fn expect_names_body_count_and_bounding_box_mismatches() { + let mut s = server(); + let box40 = json!({"command": "solid.box", "params": {"length": 40, "width": 30, "height": 20, "corner": [0, 0, 0]}}); + let cube = json!({"command": "solid.box", "params": {"length": 10, "width": 10, "height": 10, "corner": [100, -5, -5]}}); + let r = raw_tool( + &mut s, + "batch", + json!({"commands": [box40, cube], "expect": {"volume_mm3": 25000, "bodies": 1, "bbox": {"min": [0, 0, 0], "max": [40, 30, 20]}}}), + ); + assert_eq!(r["result"]["isError"], true, "{r}"); + let body: Value = serde_json::from_str(r["result"]["content"][1]["text"].as_str().unwrap()).unwrap(); + let mismatch = body["expectation"]["mismatch"].as_array().unwrap(); + assert_eq!(mismatch.len(), 2, "the volume matches and is not named: {body}"); + assert_eq!(mismatch[0], "bodies: measured 2, expected 1", "{body}"); + let bbox = mismatch[1].as_str().unwrap(); + assert!(bbox.starts_with("bbox: measured min [0, -5, -5] max [110, 30, 20], expected min [0, 0, 0] max [40, 30, 20] ("), "{bbox}"); + assert!(bbox.contains("min y off by -5 mm") && bbox.contains("min z off by -5 mm") && bbox.contains("max x off by 70 mm"), "{bbox}"); + assert!(!bbox.contains("max y") && !bbox.contains("max z") && !bbox.contains("min x"), "{bbox}"); + assert_eq!(body["expectation"]["measured"]["bodies"], 2, "{body}"); + assert!(rel(body["expectation"]["measured"]["bbox"]["max"][0].as_f64().unwrap(), 110.0) < 1e-6, "{body}"); + assert_eq!(tool(&mut s, "measure", json!({}))["body_count"], 2, "the design is kept"); + // Within 0.05 mm the box matches; past it the coordinate is named. + tool(&mut s, "undo", json!({})); + let r = tool(&mut s, "batch", json!({"commands": [{"command": "redo"}], "expect": {"bbox": {"min": [0, -5, -5.04], "max": [110.04, 30, 20]}}})); + assert_eq!(r["expectation"]["ok"], true, "{r}"); + let r = raw_tool(&mut s, "batch", json!({"commands": [{"command": "undo"}], "expect": {"bbox": {"min": [0, 0, 0], "max": [40.1, 30, 20]}}})); + assert_eq!(r["result"]["isError"], true, "{r}"); + assert!(r["result"]["content"][0]["text"].as_str().unwrap().contains("(max x off by -0.1 mm)"), "{r}"); + // No body at all: the box can't be measured, and the count says so. + tool(&mut s, "new_design", json!({})); + let r = raw_tool( + &mut s, + "batch", + json!({"commands": [{"command": "parameters.add", "params": {"name": "w", "expression": "1 mm"}}], "expect": {"bodies": 1, "bbox": {"min": [0, 0, 0], "max": [1, 1, 1]}}}), + ); + assert_eq!(r["result"]["isError"], true, "{r}"); + let body: Value = serde_json::from_str(r["result"]["content"][1]["text"].as_str().unwrap()).unwrap(); + assert_eq!( + body["expectation"]["mismatch"], + json!(["bodies: measured 0, expected 1", "bbox: no body to measure, expected min [0, 0, 0] max [1, 1, 1]"]), + "{body}" + ); + assert!(body["expectation"]["measured"]["bbox"].is_null(), "{body}"); +} + +/// An `expect` that is not what the schema says is refused before anything runs: a typo never +/// builds a design that then goes unchecked. +#[test] +fn a_malformed_expect_is_refused_before_anything_runs() { + let mut s = server(); + let step = json!({"command": "solid.box", "params": {"length": 10, "width": 10, "height": 10}}); + for name in ["execute", "batch"] { + let args = |expect: Value| { + let mut a = if name == "batch" { json!({"commands": [step]}) } else { step.clone() }; + a["expect"] = expect; + a + }; + // Not an object: the argument check, as for every tool argument. + for bad in [json!(5), json!("24000"), json!([24000]), json!(true)] { + let r = raw_tool(&mut s, name, args(bad.clone())); + assert_eq!(r["error"]["code"], -32602, "{name} {bad}: {r}"); + assert!(r["error"]["message"].as_str().unwrap().contains("`expect` must be of type"), "{r}"); + } + // An object the tool can't use: a tool error naming the key, and nothing was run. + for (bad, says) in [ + (json!({}), "nothing to check"), + (json!({"volume": 24000}), "unknown key `volume`"), + (json!({"volume_mm3": "24000"}), "`volume_mm3` must be a number"), + (json!({"volume_mm3": -1}), "`volume_mm3` must not be negative"), + (json!({"volume_mm3": 1, "tol": -0.1}), "`tol` must not be negative"), + (json!({"bodies": 1.5}), "`bodies` must be a whole number"), + (json!({"bodies": -1}), "`bodies` must be a whole number"), + (json!({"bbox": [0, 0, 0]}), "`bbox` must be"), + (json!({"bbox": {"min": [0, 0], "max": [1, 1, 1]}}), "`bbox.min` must be [x, y, z]"), + (json!({"bbox": {"min": [0, 0, 0], "max": [1, "1", 1]}}), "`bbox.max` must be [x, y, z]"), + (json!({"bbox": {"min": [2, 0, 0], "max": [1, 1, 1]}}), "`bbox.min` must not exceed"), + (json!({"bbox": {"min": [0, 0, 0], "max": [1, 1, 1], "mid": [0, 0, 0]}}), "unknown key `bbox.mid`"), + ] { + let r = raw_tool(&mut s, name, args(bad.clone())); + assert_eq!(r["result"]["isError"], true, "{name} {bad}: {r}"); + let text = r["result"]["content"][0]["text"].as_str().unwrap(); + assert!(text.starts_with("expect: ") && text.contains(says), "{name} {bad}: {text}"); + } + assert_eq!(tool(&mut s, "measure", json!({}))["body_count"], 0, "{name}: nothing ran"); + assert_eq!(tool(&mut s, "inspect_design", json!({"measure": false}))["undo"], 0, "{name}: nothing ran"); + } +} + +/// `execute` takes `expect` as `batch` does: met, the reply carries the expectation; not met, +/// the reply is an error naming it, and the command's result stays, as the design does. A +/// command that fails is the error it always was, with nothing measured. +#[test] +fn execute_checks_its_expect_like_batch() { + let mut s = server(); + let r = tool( + &mut s, + "execute", + json!({ + "command": "solid.box", "params": {"length": 40, "width": 30, "height": 20, "corner": [0, 0, 0]}, + "expect": {"volume_mm3": 24000, "bodies": 1, "bbox": {"min": [0, 0, 0], "max": [40, 30, 20]}}, + }), + ); + assert_eq!(r["created_bodies"], json!(["Body1"]), "{r}"); + assert_eq!(r["expectation"]["ok"], true, "{r}"); + assert_eq!(r["expectation"]["mismatch"], json!([]), "{r}"); + let r = raw_tool( + &mut s, + "execute", + json!({ + "command": "solid.box", "params": {"length": 10, "width": 10, "height": 10, "corner": [15, 10, 5], "operation": "cut"}, + "verbose": false, + "expect": {"volume_mm3": 24000, "bodies": 2}, + }), + ); + assert_eq!(r["result"]["isError"], true, "{r}"); + let content = r["result"]["content"].as_array().unwrap(); + let first = content[0]["text"].as_str().unwrap(); + assert!(first.starts_with("expectation not met: volume: measured 23000, expected 24000 (-4.17 %); bodies: measured 1, expected 2."), "{first}"); + let body: Value = serde_json::from_str(content[1]["text"].as_str().unwrap()).unwrap(); + assert_eq!(body["changed_bodies"], json!(["Body1"]), "the command's result stays: {body}"); + assert!(body.get("bodies").is_none(), "compact, as asked: {body}"); + assert_eq!(body["expectation"]["measured"]["bodies"], 1, "{body}"); + assert!(rel(volume(&mut s), 23000.0) < 1e-9, "the cut is kept"); + let r = raw_tool(&mut s, "execute", json!({"command": "solid.extrude", "params": {"distance": 10}, "expect": {"bodies": 1}})); + assert_eq!(r["result"]["isError"], true, "{r}"); + assert_eq!(r["result"]["content"].as_array().map(Vec::len), Some(1), "{r}"); + assert!(!r["result"]["content"][0]["text"].as_str().unwrap().contains("expectation"), "{r}"); + assert!(rel(volume(&mut s), 23000.0) < 1e-9); +} + #[test] fn helper_sketches_can_be_hidden() { let mut s = server(); @@ -2145,6 +2352,28 @@ fn batch_reports_a_failed_engine_batch_like_before() { ); } +/// Bridged, `expect` measures the app's design with one `inspect.measure` after the one +/// `engine.batch` request, and a batch that failed is not measured. +#[test] +fn a_bridged_batch_measures_its_expect_after_the_one_batch_call() { + let steps = json!([{"command": "a.one"}]); + let reply = json!({"completed": 1, "results": [{"x": 1}], "undone": 0}); + let mut b = Recorder { calls: Vec::new(), batch: Ok(reply.clone()) }; + let r = crate::tools::call_tool(&mut b, "batch", &json!({"commands": steps, "expect": {"bodies": 1}})); + assert_eq!(methods(&b), ["engine.batch", "engine.execute"]); + assert_eq!(b.calls[1].1, json!({"command": "inspect.measure", "params": {}})); + // The recorder's measure reply has no bodies: the mismatch comes first, the batch's reply after it. + assert_eq!(r["isError"], json!(true), "{r}"); + assert!(r["content"][0]["text"].as_str().unwrap().starts_with("expectation not met: bodies: measured 0, expected 1."), "{r}"); + let body: Value = serde_json::from_str(r["content"][1]["text"].as_str().unwrap()).unwrap(); + assert_eq!((body["ok"].clone(), body["completed"].clone(), body["expectation"]["ok"].clone()), (json!(true), json!(1), json!(false)), "{body}"); + let failed = json!({"completed": 0, "results": [], "failed": {"index": 0, "command": "a.one", "error": "boom"}, "undone": 0}); + let (b, body, is_error) = recorded_batch(Ok(failed), json!({"commands": steps, "expect": {"bodies": 1}})); + assert!(is_error); + assert_eq!(methods(&b), ["engine.batch"], "a failed batch is not measured"); + assert!(body.get("expectation").is_none(), "{body}"); +} + /// `rolled_back` tells whether the design went back, not whether a rollback was asked for /// (#3242): the app's `rolled_back`, or, for an app that predates that field, none of the /// completed steps undone means the design did not go back. diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rs index cc98dbc09..a47205654 100644 --- a/crates/mcp/src/tools.rs +++ b/crates/mcp/src/tools.rs @@ -13,6 +13,10 @@ use crate::backend::{Backend, STILL_RUNNING}; const MAX_BATCH: usize = 10_000; /// Largest image returned by `screenshot`. const MAX_IMAGE_BYTES: usize = 32 << 20; +/// Relative tolerance on an expected volume (`expect.tol`) when the call gives none. +const EXPECT_VOLUME_TOL: f64 = 0.002; +/// Absolute tolerance on each expected bounding-box coordinate, mm. +const EXPECT_BBOX_TOL_MM: f64 = 0.05; const VIEWS: &[&str] = &["iso", "home", "front", "back", "top", "bottom", "left", "right", "fit"]; /// What `check_parameters` can report. @@ -60,6 +64,34 @@ fn string(desc: &str) -> Value { json!({"type": "string", "description": desc}) } +/// The `expect` argument of `execute` and `batch`: what the design should measure once the +/// call has gone through. +fn expect_schema() -> Value { + json!({ + "type": "object", + "description": "Check the design after the call against the numbers you computed: {volume_mm3?, tol? (relative, default 0.002), \ + bodies?, bbox?: {min: [x,y,z], max: [x,y,z]} (each coordinate within 0.05 mm)}. The reply gains `expectation`: \ + {ok, measured: {volume_mm3, bodies, bbox}, expected, mismatch: [\"volume: measured X, expected Y (+Z %)\", ...]}. \ + A mismatch is a tool error that names it first; the design is kept as built, so inspect it and fix it or carry on", + "properties": { + "volume_mm3": {"type": "number", "description": "Total volume of the closed bodies, mm³"}, + "tol": {"type": "number", "description": "Relative tolerance on the volume (default 0.002)"}, + "bodies": {"type": "integer", "description": "Number of bodies"}, + "bbox": { + "type": "object", + "description": "Bounding box of all bodies together, mm, each coordinate within 0.05 mm", + "properties": { + "min": {"type": "array", "items": {"type": "number"}, "minItems": 3, "maxItems": 3}, + "max": {"type": "array", "items": {"type": "number"}, "minItems": 3, "maxItems": 3}, + }, + "required": ["min", "max"], + "additionalProperties": false, + }, + }, + "additionalProperties": false, + }) +} + /// Every tool, with its JSON schema. The same list serves the headless and the bridged backend. pub fn tool_definitions() -> Vec { vec![ @@ -95,12 +127,14 @@ pub fn tool_definitions() -> Vec { after a delete (undo rewinds the counters with the design), usable right away \ in sketch.dimension, sketch.constraint.* and sketch.delete. Feature commands return the feature's id \ and name, every body (bodies) and the bodies the feature created, changed and removed (created_bodies, changed_bodies, removed_bodies). \ - view.pick {pixels: [[x,y]…]} answers the body, face, exact world point, normal and depth under pixels of a screenshot (read-only; docs/control-protocol.md).", + view.pick {pixels: [[x,y]…]} answers the body, face, exact world point, normal and depth under pixels of a screenshot (read-only; docs/control-protocol.md). \ + `expect` {volume_mm3, tol, bodies, bbox} checks the design after the command (as `batch` does) and flags a mismatch.", obj( json!({ "command": string("Command id (see list_commands)"), "params": {"type": "object", "description": "The command's parameters"}, "verbose": {"type": "boolean", "description": "false: omit the full feature body list and sketch ids repeated outside `created`; keep created_bodies, changed_bodies and removed_bodies (default true)"}, + "expect": expect_schema(), }), &["command"], ), @@ -119,7 +153,9 @@ pub fn tool_definitions() -> Vec { rollback: false), so the batch is all-or-nothing; the reply names the failing step (index from 0), its error, \ every result before it, whether the design really went back (rolled_back), the steps whose changes are in the \ design (applied) and those never sent (not_run). The usual way to build a part: sketch, draw, dimension, \ - finish, extrude, fillet… in one call.", + finish, extrude, fillet… in one call. Give `expect` {volume_mm3, tol, bodies, bbox} with the numbers you computed \ + beforehand: after the last step the design is measured and compared, so no separate measure call is needed; a \ + mismatch is flagged as an error naming it, and the design is kept as built.", obj( json!({ "commands": { @@ -132,6 +168,7 @@ pub fn tool_definitions() -> Vec { "timings": {"type": "boolean", "description": "Add `timings`: [{index, command, ms}] for every step run (the failing one included) and `total_ms` (default false)"}, "profile": {"type": "boolean", "description": "Like timings, and each step's `profile`: {boolean_ms, tessellate_ms, other_ms}, its time in kernel booleans, in tessellation and the rest (default false)"}, "verbose": {"type": "boolean", "description": "false: a compact reply. Feature steps leave out the full body list (created_bodies, changed_bodies and removed_bodies stay), sketch steps the ids they repeat outside `created` (default true)"}, + "expect": expect_schema(), }), &["commands"], ), @@ -461,6 +498,7 @@ pub fn call_tool(b: &mut dyn Backend, name: &str, args: &Value) -> Value { "screenshot" => return screenshot(b, a), "batch" => return batch(b, a), "check_parameters" => return check_parameters(b, a), + "execute" => return execute(b, a), _ => dispatch(b, name, a), }; match r { @@ -469,6 +507,213 @@ pub fn call_tool(b: &mut dyn Backend, name: &str, args: &Value) -> Value { } } +/// `execute`: one command, then its `expect` checked against the design. +fn execute(b: &mut dyn Backend, a: &Map) -> Value { + let expect = match Expect::parse(a) { + Ok(e) => e, + Err(e) => return text_result(&Value::String(e), true), + }; + match dispatch(b, "execute", a) { + Ok(v) => with_expectation(b, v, expect), + Err(e) => text_result(&Value::String(e), true), + } +} + +/// What `execute` or `batch` was told the design would measure once the call went through +/// (`expect`): the numbers an agent computes before building, compared by the server instead +/// of by hand after a separate `measure` call. Volume and body count hold whatever kernel +/// builds the design. +struct Expect { + volume_mm3: Option, + tol: f64, + bodies: Option, + bbox: Option<([f64; 3], [f64; 3])>, +} + +impl Expect { + /// The tool's `expect` argument: `None` when it was not given. A malformed one is refused + /// before the call runs, so a typo never builds a design that then goes unchecked. + fn parse(a: &Map) -> Result, String> { + let Some(v) = a.get("expect").filter(|v| !v.is_null()) else { return Ok(None) }; + let Some(o) = v.as_object() else { return Err("expect: must be an object {volume_mm3?, tol?, bodies?, bbox?}".into()) }; + if let Some(k) = o.keys().find(|k| !["volume_mm3", "tol", "bodies", "bbox"].contains(&k.as_str())) { + let k: String = k.chars().take(64).collect(); + return Err(format!("expect: unknown key `{k}`; its keys are: volume_mm3, tol, bodies, bbox")); + } + let number = |k: &str| -> Result, String> { + match o.get(k) { + None | Some(Value::Null) => Ok(None), + Some(v) => v.as_f64().filter(|x| x.is_finite()).map(Some).ok_or_else(|| format!("expect: `{k}` must be a number")), + } + }; + let volume_mm3 = number("volume_mm3")?; + if volume_mm3.is_some_and(|v| v < 0.0) { + return Err("expect: `volume_mm3` must not be negative".into()); + } + let tol = number("tol")?.unwrap_or(EXPECT_VOLUME_TOL); + if tol < 0.0 { + return Err("expect: `tol` must not be negative".into()); + } + let bodies = match o.get("bodies") { + None | Some(Value::Null) => None, + Some(v) => Some(v.as_u64().ok_or("expect: `bodies` must be a whole number, 0 or more")?), + }; + let bbox = match o.get("bbox") { + None | Some(Value::Null) => None, + Some(v) => Some(Self::parse_bbox(v)?), + }; + if volume_mm3.is_none() && bodies.is_none() && bbox.is_none() { + return Err("expect: nothing to check; give volume_mm3, bodies or bbox".into()); + } + Ok(Some(Expect { volume_mm3, tol, bodies, bbox })) + } + + fn parse_bbox(v: &Value) -> Result<([f64; 3], [f64; 3]), String> { + let Some(o) = v.as_object() else { return Err("expect: `bbox` must be {min: [x,y,z], max: [x,y,z]} in mm".into()) }; + if let Some(k) = o.keys().find(|k| !["min", "max"].contains(&k.as_str())) { + let k: String = k.chars().take(64).collect(); + return Err(format!("expect: unknown key `bbox.{k}`; its keys are: min, max")); + } + let corner = |k: &str| -> Result<[f64; 3], String> { + let err = || format!("expect: `bbox.{k}` must be [x, y, z] in mm"); + let xyz = o.get(k).and_then(Value::as_array).filter(|a| a.len() == 3).ok_or_else(err)?; + let mut c = [0.0; 3]; + for (slot, x) in c.iter_mut().zip(xyz) { + *slot = x.as_f64().filter(|x| x.is_finite()).ok_or_else(err)?; + } + Ok(c) + }; + let (min, max) = (corner("min")?, corner("max")?); + if min.iter().zip(&max).any(|(lo, hi)| lo > hi) { + return Err("expect: `bbox.min` must not exceed `bbox.max`".into()); + } + Ok((min, max)) + } + + /// What was expected, for the reply. + fn expected(&self) -> Value { + let mut e = Map::new(); + if let Some(v) = self.volume_mm3 { + e.insert("volume_mm3".into(), json!(v)); + e.insert("tol".into(), json!(self.tol)); + } + if let Some(n) = self.bodies { + e.insert("bodies".into(), json!(n)); + } + if let Some((min, max)) = self.bbox { + e.insert("bbox".into(), json!({"min": min, "max": max})); + } + Value::Object(e) + } + + /// Measure the design (as the `measure` tool does) and compare: the reply's `expectation` + /// (`ok`, `measured`, `expected`, `mismatch`). + fn check(&self, b: &mut dyn Backend) -> Result { + let m = exec(b, "inspect.measure", json!({}))?; + let bodies = m["body_count"].as_u64().unwrap_or(0); + let volume = m["total"]["volume_mm3"].as_f64(); + let bbox = m["bodies"].as_array().into_iter().flatten().filter_map(|body| corners(&body["bbox"])).reduce(|(lo, hi), (min, max)| { + ([lo[0].min(min[0]), lo[1].min(min[1]), lo[2].min(min[2])], [hi[0].max(max[0]), hi[1].max(max[1]), hi[2].max(max[2])]) + }); + let mut mismatch: Vec = Vec::new(); + if let Some(e) = self.volume_mm3 { + match volume { + Some(v) if (v - e).abs() <= self.tol * e.abs() => {} + Some(v) => { + let pct = if e != 0.0 { format!(" ({:+.2} %)", (v - e) / e * 100.0) } else { String::new() }; + mismatch.push(format!("volume: measured {}, expected {}{pct}", num(v), num(e))); + } + None => mismatch.push(format!("volume: not measured (no closed body), expected {}", num(e))), + } + } + if let Some(e) = self.bodies + && bodies != e + { + mismatch.push(format!("bodies: measured {bodies}, expected {e}")); + } + if let Some((emin, emax)) = self.bbox { + let expected = format!("min {} max {}", xyz_text(emin), xyz_text(emax)); + match bbox { + Some((min, max)) => { + let off: Vec = [("min", min, emin), ("max", max, emax)] + .into_iter() + .flat_map(|(side, m, e)| { + ["x", "y", "z"] + .into_iter() + .zip(m) + .zip(e) + .filter(|&((_, m), e)| (m - e).abs() > EXPECT_BBOX_TOL_MM) + .map(move |((axis, m), e)| format!("{side} {axis} off by {} mm", num(m - e))) + }) + .collect(); + if !off.is_empty() { + mismatch.push(format!( + "bbox: measured min {} max {}, expected {expected} ({})", + xyz_text(min), + xyz_text(max), + off.join(", ") + )); + } + } + None => mismatch.push(format!("bbox: no body to measure, expected {expected}")), + } + } + Ok(json!({ + "ok": mismatch.is_empty(), + "measured": {"volume_mm3": volume, "bodies": bodies, "bbox": bbox.map(|(min, max)| json!({"min": min, "max": max}))}, + "expected": self.expected(), + "mismatch": mismatch, + })) + } +} + +/// `{min: [x,y,z], max: [x,y,z]}` as two corners. +fn corners(v: &Value) -> Option<([f64; 3], [f64; 3])> { + let xyz = |k: &str| -> Option<[f64; 3]> { + let a = v.get(k)?.as_array()?; + Some([a.first()?.as_f64()?, a.get(1)?.as_f64()?, a.get(2)?.as_f64()?]) + }; + Some((xyz("min")?, xyz("max")?)) +} + +/// A number in a mismatch message: at most four decimals, no trailing zeros. +fn num(x: f64) -> String { + let r = (x * 1e4).round() / 1e4; + // `-0` for a coordinate a hair under zero would read as a sign error. + format!("{}", if r == 0.0 { 0.0 } else { r }) +} + +fn xyz_text(c: [f64; 3]) -> String { + format!("[{}, {}, {}]", num(c[0]), num(c[1]), num(c[2])) +} + +/// A reply that went through, with its `expectation` when `expect` was given. A mismatch is a +/// tool error that names it first; the design stays as built (the agent decides what to do). +fn with_expectation(b: &mut dyn Backend, mut reply: Value, expect: Option) -> Value { + let Some(expect) = expect else { return text_result(&reply, false) }; + let expectation = match expect.check(b) { + Ok(e) => e, + Err(e) => json!({"ok": false, "expected": expect.expected(), "mismatch": [format!("the design could not be measured: {e}")]}), + }; + let mismatch: Vec<&str> = expectation["mismatch"].as_array().into_iter().flatten().filter_map(Value::as_str).collect(); + let note = (expectation["ok"] != true).then(|| { + format!( + "expectation not met: {}. The design is kept as built: inspect it, then fix it (timeline.edit, undo) or carry on.", + mismatch.join("; ") + ) + }); + if !reply.is_object() { + reply = json!({"result": reply}); + } + reply["expectation"] = expectation; + let Some(note) = note else { return text_result(&reply, false) }; + let mut r = text_result(&reply, true); + if let Some(content) = r["content"].as_array_mut() { + content.insert(0, json!({"type": "text", "text": note})); + } + r +} + fn exec(b: &mut dyn Backend, command: &str, params: Value) -> Result { b.call("engine.execute", json!({"command": command, "params": params})).map_err(|error| command_error(command, error)) } @@ -818,13 +1063,26 @@ impl Undo { } /// `batch`: run steps in order, stop at the first failure and (by default) go back to the -/// design as it was before the batch. +/// design as it was before the batch. A batch that went through is then checked against its +/// `expect`. fn batch(b: &mut dyn Backend, a: &Map) -> Value { + let expect = match Expect::parse(a) { + Ok(e) => e, + Err(e) => return text_result(&Value::String(e), true), + }; + match batch_run(b, a) { + (reply, true) => text_result(&reply, true), + (reply, false) => with_expectation(b, reply, expect), + } +} + +/// The batch itself: its reply and whether it failed. +fn batch_run(b: &mut dyn Backend, a: &Map) -> (Value, bool) { let Some(steps) = a.get("commands").and_then(Value::as_array) else { - return text_result(&json!("`commands` must be an array of {command, params}"), true); + return (json!("`commands` must be an array of {command, params}"), true); }; if steps.len() > MAX_BATCH { - return text_result(&json!(format!("batch too long ({} steps, at most {MAX_BATCH})", steps.len())), true); + return (json!(format!("batch too long ({} steps, at most {MAX_BATCH})", steps.len())), true); } let rollback = a.get("rollback").and_then(Value::as_bool).unwrap_or(true); let verbose = a.get("verbose").and_then(Value::as_bool).unwrap_or(true); @@ -869,7 +1127,7 @@ fn batch(b: &mut dyn Backend, a: &Map) -> Value { "results": [], "note": "nothing was run", }); - return text_result(&reply, true); + return (reply, true); } } } @@ -888,7 +1146,7 @@ fn batch(b: &mut dyn Backend, a: &Map) -> Value { 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); + return (reply, true); } // A tool step's result as the tool would reply it: a `list_commands` step's catalog filtered, // a `measure {summary: true}` step's reply summarised. @@ -926,12 +1184,12 @@ fn batch(b: &mut dyn Backend, a: &Map) -> Value { // Never sent: no app to send it to. Or sent and still running (it was not cancelled): // the `pending` tool gets its result. Err(e) if e.starts_with(crate::backend::NOT_RUNNING) || e.starts_with(STILL_RUNNING) => { - return text_result(&Value::String(e), true); + return (Value::String(e), true); } // The app may have run it: sending the steps again would apply them twice. Err(e) => { let msg = format!("the app did not answer engine.batch ({e}); it may have run: inspect the design before sending it again"); - return text_result(&Value::String(msg), true); + return (Value::String(msg), true); } } } @@ -1001,14 +1259,14 @@ fn batch(b: &mut dyn Backend, a: &Map) -> Value { "not_run": (i + 1..steps.len()).collect::>(), "results": results, }); - return text_result(&with_timings(reply, timed, rows, clock.ms()), true); + return (with_timings(reply, timed, rows, clock.ms()), true); } } } } start.finish(b); let reply = json!({"ok": true, "completed": results.len(), "results": results}); - text_result(&with_timings(reply, timed, rows, clock.ms()), false) + (with_timings(reply, timed, rows, clock.ms()), false) } /// `reply` with `timings` and `total_ms` when they were asked for. @@ -1021,7 +1279,7 @@ fn with_timings(mut reply: Value, timed: bool, rows: Vec, total_ms: f64) } /// The `batch` reply from the app's `engine.batch` answer, shaped as the per-step path shapes it. -fn batch_reply(r: &Value, len: usize, rollback: bool, verbose: bool, narrow: &dyn Fn(usize, Value) -> Value) -> Value { +fn batch_reply(r: &Value, len: usize, rollback: bool, verbose: bool, narrow: &dyn Fn(usize, Value) -> Value) -> (Value, bool) { let results: Vec = r["results"] .as_array() .cloned() @@ -1065,7 +1323,7 @@ fn batch_reply(r: &Value, len: usize, rollback: bool, verbose: bool, narrow: &dy } } } - text_result(&reply, error) + (reply, error) } /// `measure {summary: true}`: an `inspect.measure` reply cut down to what checks a stage against diff --git a/docs/mcp.md b/docs/mcp.md index 91f402f82..d6556db16 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -287,8 +287,28 @@ 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` (`summary: true` summarised as the tool summarises it), `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`, `check_parameters`, `pending`, `running` and `skill_reference` can't be steps, nor can `component.edit_in_place` and `component.finish_edit`, however a step names them, as they go to another design's tab (send them with the `execute` tool on their own): 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, and a bridged server at `--param-check strict` checks the contracts before it sends 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. | +| `execute` | `command`, `params?`, `verbose?` (default true), `expect?` | 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`. `expect` checks the design after the command, as it does for `batch` (see below). | +| `batch` | `commands: [{command, params}]`, `rollback?` (default true), `verbose?` (default true), `timings?`, `profile?`, `coalesce_parameters?` (default false), `expect?` | 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` (`summary: true` summarised as the tool summarises it), `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`, `check_parameters`, `pending`, `running` and `skill_reference` can't be steps, nor can `component.edit_in_place` and `component.finish_edit`, however a step names them, as they go to another design's tab (send them with the `execute` tool on their own): 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, and a bridged server at `--param-check strict` checks the contracts before it sends 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. | + +**`expect`** on `batch` and `execute` turns the verify step into part of the build. An agent +computes the volume, body count or bounding box a stage should produce before building it; +instead of a `measure` call and a comparison by hand after every stage, it gives them to the +call: `"expect": {"volume_mm3": 59824.9, "tol": 0.002, "bodies": 1, "bbox": {"min": [0, 0, 0], +"max": [140, 90, 30]}}`. Every key is optional (at least one of `volume_mm3`, `bodies` and `bbox`); +`tol` is relative to the expected volume (default 0.002, so 0.2 %), and each bounding-box +coordinate must lie within 0.05 mm. Once the call has gone through, the server measures the +design the way `measure` does (the total volume of the closed bodies, the body count and the +box round every body) and the reply gains +`"expectation": {"ok": bool, "measured": {"volume_mm3", "bodies", "bbox"}, "expected": {...}, "mismatch": ["volume: measured 59680, expected 59824.9 (-0.24 %)", ...]}`. +On a mismatch the tool result is flagged `isError: true`, with the mismatch text as its first +content block and the reply as the second, so the model notices; the design is kept as built +(undoably, as ever), and the agent decides whether to undo, edit a feature (`timeline.edit`) or +carry on. A batch that fails is not measured, and an `expect` the tool cannot use (an unknown key, +a value of the wrong type, a negative `tol`, a `bbox` without three coordinates a side) is +refused before anything runs. `expect` is an argument of the tool, not a key of a step: a step +carrying one is treated as any step with a key the batch does not know. Volume and body count +say nothing about which kernel built the design, which is the point: the check holds whatever +builds it. | `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?`, `summary?` (default false) | 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. `summary: true` keeps one short object per body (`name`, `volume_mm3`, `bbox: {min, max}`, `faces`, `closed`; a body that could not be measured keeps its `error`), `body_count` and `total.volume_mm3`, nothing else: what a stage check against computed numbers needs, at a fraction of the size. It applies to the bodies reply, not to `items`. | | `body_topology` | `body`, `faces?` (`all`, `cylinders`; default `all`) | 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`). `faces: "cylinders"` replies `cylinders` instead of `edges` and `faces`: one entry per cylinder, `{radius, origin, axis, extent, names}`, the halves the kernel splits a cylinder into merged (same radius, same axis line; `origin` and `axis` as the first half's `cylinder` gives them), `extent` the `[min, max]` distance along `axis` from `origin` that the body's points on the cylinder span (the faces' `point`s and the ends of the edges lying on it; left out when none were found), and `names` the merged faces' names, any of which picks the face. Enough to check where every hole and boss is, in a few lines instead of the whole topology. |