SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
MCP: wait out long requests, honest batch outcomes, batch tool aliases (#2901)
SS-EN6c6ffe480210
diff --git a/apps/solidcraft/src/control_server.rs b/apps/solidcraft/src/control_server.rsindex c64f210795..ea4a65d4dc 100644--- a/apps/solidcraft/src/control_server.rs+++ b/apps/solidcraft/src/control_server.rs@@ -11,6 +11,7 @@ use std::time::{Duration, Instant};use serde_json::{Value, json};use solidcraft_engine::MAX_LINE;use solidcraft_engine::control_auth;+use solidcraft_engine::control_pending;use solidcraft_ui_egui::ControlRequest;/// Connections served at once, so a flood must not be able to spawn threads without end.@@ -204,6 +205,8 @@ const WAITS: Waits = Waits { short: Duration::from_secs(60), long: Duration::frostruct Pending {id: Value,method: String,+ /// The request in messages ("`engine.execute` (solid.fillet)").+ what: String,reply: Receiver<Value>,}@@ -324,6 +327,35 @@ fn watch(reply: Receiver<Value>, ticket: Ticket) -> Receiver<Value> {late_rx}+/// The reply text for a request that outlasts its wait. A request that only reads changes+/// nothing when it finishes; an export or a save still writes its file, and any other request+/// still applies, as it was not cancelled.+fn timeout_message(what: &str, effect: control_pending::Effect) -> String {+ match effect {+ control_pending::Effect::ReadsOnly => {+ format!("timeout: {what} is still running in the app ({}); ask `control.pending` for its answer", effect.when_done())+ }+ control_pending::Effect::WritesFile => format!(+ "timeout: {what} is still running in the app and will still write the file when it finishes (it was not cancelled: \+ don't send it again; the design does not change); ask `control.pending` for its result"+ ),+ control_pending::Effect::Changes => format!(+ "timeout: {what} is still running in the app and will still apply when it finishes (it was not cancelled: don't send it \+ again); ask `control.pending` for its result"+ ),+ }+}++/// The reply text for a request refused because an earlier one on the connection still runs.+fn busy_message(p: &Pending, method: &str) -> String {+ let method: String = method.chars().take(128).collect();+ format!(+ "busy: request {} ({}) is still running, so `{method}` was not run; ask `control.pending` for that request's result, then \+ send this one again",+ p.id, p.what+ )+}+fn serve(stream: TcpStream, token: &str, tx: Sender<ControlRequest>, ctx: egui::Context, patient: bool) {serve_with(stream, token, tx, ctx, patient, WAITS, &RUNNING);}@@ -392,7 +424,7 @@ fn serve_with(}} else if let Some(p) = pending.as_ref().filter(|_| late.is_none()) {// Nothing more is queued behind it, to run unseen when it ends.- json!({"ok": false, "busy": true, "error": format!("busy: request {} (`{}`) is still running; ask `control.pending` for its result", p.id, p.method)})+ json!({"ok": false, "busy": true, "error": busy_message(p, &method)})} else {if late.is_some() {// Finished, and the client moved on without asking: it is dropped.@@ -400,6 +432,8 @@ fn serve_with(}// A batch replaces many short requests: the whole of it may take long (#743).let wait = if patient || method == "engine.batch" { waits.long } else { waits.short };+ let what = control_pending::describe(&method, ¶ms);+ let effect = control_pending::effect(&method, ¶ms);let (req, rrx) = ControlRequest::new(method.clone(), params);let ticket = running.add(connection, &id, &req);if tx.send(req).is_err() {@@ -409,8 +443,8 @@ fn serve_with(match rrx.recv_timeout(wait) {Ok(r) => r,Err(_) => {- let r = json!({"ok": false, "running": true, "error": format!("timeout: `{method}` is still running in the app and will still apply; ask `control.pending` for its result")});- pending = Some(Pending { id: id.clone(), method, reply: watch(rrx, ticket) });+ let r = json!({"ok": false, "running": true, "error": timeout_message(&what, effect)});+ pending = Some(Pending { id: id.clone(), method, what, reply: watch(rrx, ticket) });r}}@@ -605,6 +639,25 @@ mod tests {assert_eq!((&r["result"]["pending"], &r["result"]["done"]), (&json!(7), &json!(true)), "{r}");}+ /// A timed-out request that only reads is not said to "still apply", nor is one that only+ /// writes a file (an export, #1989); a change is, by name.+ #[test]+ fn timeout_text_tells_reads_from_changes() {+ let says = |method: &str, p: Value| timeout_message(&control_pending::describe(method, &p), control_pending::effect(method, &p));+ let read = says("ui.inspect", json!({}));+ assert!(read.starts_with("timeout") && read.contains("only reads") && !read.contains("will still apply"), "{read}");+ let read = says("engine.execute", json!({"command": "sketch.inspect"}));+ assert!(read.contains("only reads") && read.contains("sketch.inspect"), "{read}");+ let change = says("engine.execute", json!({"command": "solid.fillet"}));+ assert!(change.starts_with("timeout") && change.contains("will still apply") && change.contains("solid.fillet"), "{change}");+ let export = says("engine.execute", json!({"command": "file.export", "params": {"path": "/tmp/wall.step"}}));+ assert!(export.contains("will still write the file") && !export.contains("apply") && export.contains("file.export"), "{export}");+ let save = says("engine.execute", json!({"command": "file.save"}));+ assert!(save.contains("will still write the file") && !save.contains("apply"), "{save}");+ let render = says("ui.render", json!({"path": "/tmp/a.png"}));+ assert!(render.contains("will still write the file"), "{render}");+ }+/// #205: a connection runs nothing until a request carries the launch's token; a wrong or/// missing token, or garbage, is refused and the connection closed. Once shown, the token/// need not be repeated on that connection.diff --git a/crates/engine/src/control_pending.rs b/crates/engine/src/control_pending.rsnew file mode 100644index 0000000000..72511bd5a4--- /dev/null+++ b/crates/engine/src/control_pending.rs@@ -0,0 +1,161 @@+//! What a client is told about a control request that outlasts its wait (docs/control-protocol.md,+//! #1618): the app's control server and the bridged MCP server both say what the request still+//! does when it finishes: nothing (it only reads), write a file (an export or a save), or change+//! the design.++use serde_json::Value;++/// What a request still running does when it finishes.+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub enum Effect {+ /// It only reads (the design, the window or the command list): nothing changes.+ ReadsOnly,+ /// It writes a file (an export, a save, a render to a path); the design stays as it is.+ WritesFile,+ /// It changes the design (or may: anything not known to read or only write a file).+ Changes,+}++impl Effect {+ /// What happens when the request finishes, for a message: "it only reads: nothing changes",+ /// "it was not cancelled and will still write the file when it finishes", …+ pub fn when_done(self) -> &'static str {+ match self {+ Effect::ReadsOnly => "it only reads: nothing changes",+ Effect::WritesFile => "it was not cancelled and will still write the file when it finishes; the design does not change",+ Effect::Changes => "it was not cancelled and will still apply when it finishes",+ }+ }+}++/// Control methods that only read: a timed-out one changes nothing when it finishes.+/// (`ui.screenshot` with a `path`, and `ui.render`, write a file: see [`effect`].)+const READ_METHODS: &[&str] = &[+ "control.pending",+ "document.inspect",+ "engine.commands",+ "ui.at",+ "ui.handles",+ "ui.inspect",+ "ui.selection",+ "ui.sketchToScreen",+ "ui.triad",+ "ui.worldToScreen",+];++/// Commands that write a file and leave the design as it is. `file.save` and `file.save_as`+/// count: they mark the design saved, but change nothing in it.+const FILE_COMMANDS: &[&str] = &["file.export", "file.save", "file.save_as", "file.save_mesh"];++/// Commands that only read the design (inspection, lists, measurements).+pub fn command_reads_only(id: &str) -> bool {+ let id = crate::find_command(id).map_or(id, |c| c.id);+ id.starts_with("inspect.")+ || id.starts_with("model.")+ || id.ends_with(".inspect")+ || id.ends_with(".list")+ || matches!(id, "document.inspect" | "engine.commands" | "render.status" | "render.backends" | "render.settings.get" | "file.slicers")+}++/// What the command `id` with `params` does: an export that is given a `path` (`*.export*`, as+/// `sketch.export_dxf` or `parameters.export`) or a save writes a file; without a path an export+/// only answers with its contents.+pub fn command_effect(id: &str, params: &Value) -> Effect {+ let id = crate::find_command(id).map_or(id, |c| c.id);+ let exports = id.split('.').skip(1).any(|part| part.starts_with("export"));+ if FILE_COMMANDS.contains(&id) || (exports && params.get("path").is_some_and(|p| !p.is_null())) {+ Effect::WritesFile+ } else if command_reads_only(id) || exports {+ Effect::ReadsOnly+ } else {+ Effect::Changes+ }+}++/// What the request `method` with `params` does when it finishes. Renders and screenshots+/// change nothing in the design; given a `path` they write it.+pub fn effect(method: &str, params: &Value) -> Effect {+ match method {+ "engine.execute" | "command" => match params.get("command").or_else(|| params.get("id")).and_then(Value::as_str) {+ Some(id) => command_effect(id, params.get("params").unwrap_or(&Value::Null)),+ None => Effect::Changes,+ },+ "ui.render" => Effect::WritesFile,+ "ui.screenshot" if params.get("path").is_some_and(|p| !p.is_null()) => Effect::WritesFile,+ "ui.screenshot" => Effect::ReadsOnly,+ m if READ_METHODS.contains(&m) => Effect::ReadsOnly,+ _ => Effect::Changes,+ }+}++/// Whether the request `method` with `params` only reads.+pub fn reads_only(method: &str, params: &Value) -> bool {+ effect(method, params) == Effect::ReadsOnly+}++/// The request in a message: "`engine.execute` (solid.fillet)", or just "`ui.inspect`".+pub fn describe(method: &str, params: &Value) -> String {+ let command = matches!(method, "engine.execute" | "command")+ .then(|| params.get("command").or_else(|| params.get("id")).and_then(Value::as_str))+ .flatten()+ .filter(|c| c.len() <= 128);+ match command {+ Some(c) => format!("`{method}` ({c})"),+ None => format!("`{}`", method.chars().take(128).collect::<String>()),+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use serde_json::json;++ #[test]+ fn reads_are_told_from_changes() {+ for (m, p) in [+ ("ui.inspect", json!({})),+ ("ui.screenshot", json!({})),+ ("document.inspect", json!({"measure": true})),+ ("engine.execute", json!({"command": "sketch.inspect"})),+ ("engine.execute", json!({"command": "inspect.measure"})),+ ("engine.execute", json!({"command": "model.edges", "params": {"body": "Body1"}})),+ ("engine.execute", json!({"command": "parameters.export", "params": {"format": "csv"}})),+ ] {+ assert!(reads_only(m, &p), "{m} {p}");+ assert_eq!(effect(m, &p), Effect::ReadsOnly, "{m} {p}");+ }+ for (m, p) in [+ ("engine.execute", json!({"command": "solid.fillet"})),+ ("engine.execute", json!({})),+ ("engine.batch", json!({"commands": []})),+ ("ui.click", json!({"x": 1, "y": 2})),+ ("app.quit", json!({})),+ ] {+ assert!(!reads_only(m, &p), "{m} {p}");+ assert_eq!(effect(m, &p), Effect::Changes, "{m} {p}");+ }+ assert_eq!(describe("engine.execute", &json!({"command": "solid.fillet"})), "`engine.execute` (solid.fillet)");+ assert_eq!(describe("ui.inspect", &json!({})), "`ui.inspect`");+ }++ /// An export or a save writes a file and leaves the design as it is (#1989: a STEP export+ /// is not said to "still apply").+ #[test]+ fn file_writers_are_told_apart() {+ for (m, p) in [+ ("engine.execute", json!({"command": "file.export", "params": {"path": "/tmp/a.step"}})),+ ("engine.execute", json!({"command": "file.save", "params": {}})),+ ("engine.execute", json!({"command": "file.save_as", "params": {"path": "/tmp/a.solidcraft"}})),+ ("engine.execute", json!({"command": "file.save_mesh", "params": {"path": "/tmp/a.stl"}})),+ ("engine.execute", json!({"command": "sketch.export_dxf", "params": {"path": "/tmp/a.dxf"}})),+ ("ui.render", json!({"path": "/tmp/a.png"})),+ ("ui.screenshot", json!({"path": "/tmp/a.png"})),+ ] {+ assert_eq!(effect(m, &p), Effect::WritesFile, "{m} {p}");+ assert!(!reads_only(m, &p), "{m} {p}");+ }+ assert!(Effect::WritesFile.when_done().contains("will still write the file") && !Effect::WritesFile.when_done().contains("apply"));+ assert!(Effect::Changes.when_done().contains("will still apply"));+ assert!(Effect::ReadsOnly.when_done().contains("nothing changes"));+ }+}diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rsindex e9cbf9d8d4..b69f500914 100644--- a/crates/engine/src/lib.rs+++ b/crates/engine/src/lib.rs@@ -10,6 +10,7 @@pub mod capture;pub mod cmd;pub mod control_auth;+pub mod control_pending;pub mod crash;pub mod frames;pub mod fuzz;diff --git a/crates/mcp/src/backend.rs b/crates/mcp/src/backend.rsindex 585a2b0904..1e168ca41a 100644--- a/crates/mcp/src/backend.rs+++ b/crates/mcp/src/backend.rs@@ -2,15 +2,18 @@use std::io::{BufRead, BufReader, Read, Write};use std::net::{TcpStream, ToSocketAddrs};-use std::time::Duration;+use std::time::{Duration, Instant};use serde_json::{Value, json};use solidcraft_engine::Session;+use solidcraft_engine::control_pending;use solidcraft_engine::render::StandardView;use solidcraft_engine::view::Guides;/// Something that answers control-channel methods: `engine.execute`, `engine.commands`,-/// `document.inspect`, `ui.view`, `ui.render`, `ui.screenshot`, `control.running`.+/// `document.inspect`, `ui.view`, `ui.render`, `ui.screenshot`, `control.running`, and+/// `control.pending` (the result of a request that was still running when its call returned:+/// `{pending: what | null, done?, reply?, lost?, running_s?}`).pub trait Backend {fn call(&mut self, method: &str, params: Value) -> Result<Value, String>;/// True when a real window is attached (`ui.screenshot` can capture it).@@ -34,8 +37,79 @@ const MAX_REPLY: u64 = 64 << 20;/// How long a reply may take: kernel operations (booleans, fillets) on big parts can take a while.const READ_TIMEOUT: Duration = Duration::from_secs(300);-/// How long the app may take to run an `engine.batch` (its control server waits as long).-const BATCH_TIMEOUT: Duration = Duration::from_secs(3600);+/// How long the app may take to run an `engine.batch`: a little longer than its control server+/// waits (3600 s), so its "still running" reply arrives first.+const BATCH_TIMEOUT: Duration = Duration::from_secs(3720);++/// How long a call goes on waiting, asking `control.pending`, after the app said its request is+/// still running (the app says so after 60 s; #1618), before it says so itself.+const PENDING_WAIT: Duration = Duration::from_secs(240);++/// How long a later call, or the `pending` tool, waits for a request still running from an+/// earlier call.+const SETTLE_WAIT: Duration = Duration::from_secs(60);++/// How often `control.pending` is asked while waiting.+const POLL_EVERY: Duration = Duration::from_millis(500);++/// How often a long wait is reported on stderr.+const PROGRESS_EVERY: Duration = Duration::from_secs(30);++/// How a tool error starts when a request is still running in the app after the wait: the+/// request was not cancelled and its reply waits on the connection; the `pending` tool gets it.+/// `batch` uses it to tell "still running" from "failed".+pub(crate) const STILL_RUNNING: &str = "still running:";++/// A request the app said is still running (#1618). Its reply will come on this connection,+/// through `control.pending`, so the connection is kept for it.+struct Outstanding {+ what: String,+ /// What it does when it finishes; `None`: not known (a request this bridge did not send).+ effect: Option<control_pending::Effect>,+ since: Instant,+}++impl Outstanding {+ fn secs(&self) -> u64 {+ self.since.elapsed().as_secs()+ }+}++/// What became of a request still running when its call returned, once a later call waited it+/// out: kept for the `pending` tool.+enum Settled {+ Finished { what: String, reply: Value },+ Lost { what: String },+}++/// The end of a wait for an outstanding request.+enum Waited {+ /// It finished: its own reply.+ Done(Value),+ /// The app holds nothing (any more) for this connection.+ Nothing,+ /// Still running when the wait ran out.+ Running,+}++/// How long to wait for a request still running (tests shorten them).+#[derive(Clone, Copy)]+pub(crate) struct Waits {+ pub pending: Duration,+ pub settle: Duration,+ pub poll: Duration,+}++const WAITS: Waits = Waits { pending: PENDING_WAIT, settle: SETTLE_WAIT, poll: POLL_EVERY };++/// A control reply as a call's result.+fn outcome(v: &Value) -> Result<Value, String> {+ if v.get("ok").and_then(Value::as_bool) == Some(true) {+ Ok(v.get("result").cloned().unwrap_or(Value::Null))+ } else {+ Err(v.get("error").and_then(Value::as_str).unwrap_or("error").to_string())+ }+}/// A running SolidCraft app reached through its loopback control port/// (`solidcraft --control PORT`).@@ -47,6 +121,11 @@ pub struct Remote {/// `--token`, when given. Otherwise each request looks the token up again, since every/// launch of the app makes a new one (docs/control-protocol.md).explicit_token: Option<String>,+ /// A request still running in the app; its reply waits on `conn`.+ outstanding: Option<Outstanding>,+ /// An outstanding request's end, once a later call waited for it (for `pending`).+ settled: Option<Settled>,+ waits: Waits,}/// How a tool error starts when no app listens at the bridged address. The agent reads it, and@@ -72,7 +151,21 @@ impl Remote {pub fn new(addr: &str, token: Option<&str>) -> Self {let port = addr.rsplit(':').next().and_then(|p| p.parse::<u16>().ok()).unwrap_or(0);let explicit_token = token.map(str::to_string);- Self { addr: addr.to_string(), port, conn: None, next_id: 1, explicit_token }+ Self { addr: addr.to_string(), port, conn: None, next_id: 1, explicit_token, outstanding: None, settled: None, waits: WAITS }+ }++ /// Shorter waits for requests still running (tests).+ #[cfg(test)]+ pub(crate) fn set_waits(&mut self, waits: Waits) {+ self.waits = waits;+ }++ /// Close the connection. A request still running loses its reply with it.+ fn drop_conn(&mut self) {+ self.conn = None;+ if let Some(o) = self.outstanding.take() {+ self.settled = Some(Settled::Lost { what: o.what });+ }}/// Connect now, if the app is there (`new` does not); the error says why not.@@ -83,7 +176,7 @@ impl Remote {/// Failing to reach the app at all is `NotConnected`, so [`Remote::explain`] can tell it from/// a connection lost during a call.fn reconnect(&mut self) -> std::io::Result<()> {- self.conn = None;+ self.drop_conn();let not_connected = |e: std::io::Error| std::io::Error::new(std::io::ErrorKind::NotConnected, e);let mut last = std::io::Error::new(std::io::ErrorKind::NotFound, format!("cannot resolve {}", self.addr));for sa in self.addr.to_socket_addrs().map_err(not_connected)? {@@ -125,7 +218,7 @@ impl Remote {// One write: a request that loses its newline still reaches the app as a request.let sent = writer.write_all(format!("{line}\n").as_bytes()).and_then(|()| writer.flush());if let Err(e) = sent {- self.conn = None;+ self.drop_conn();return Err(e);}let mut reply = String::new();@@ -133,12 +226,12 @@ impl Remote {Ok(n) => n,Err(e) => {// A timed-out read leaves a late reply on the stream: start afresh next time.- self.conn = None;+ self.drop_conn();return Err(e);}};if n == 0 || !reply.ends_with('\n') {- self.conn = None;+ self.drop_conn();return Err(std::io::Error::new(std::io::ErrorKind::UnexpectedEof, "connection closed"));}Ok(reply)@@ -162,8 +255,9 @@ impl Remote {}}-impl Backend for Remote {- fn call(&mut self, method: &str, params: Value) -> Result<Value, String> {+impl Remote {+ /// The request line for `method`: a fresh id, the agent's folders and the app's token.+ fn request_line(&mut self, method: &str, params: Value) -> String {let id = self.next_id;self.next_id += 1;let mut params = params;@@ -176,7 +270,121 @@ impl Backend for Remote {if let Some(t) = solidcraft_engine::control_auth::client_token(self.port, self.explicit_token.as_deref()) {msg["token"] = json!(t);}- let line = msg.to_string();+ msg.to_string()+ }++ /// Ask the app, on this connection only, about the request it still runs for it.+ fn ask_pending(&mut self) -> Result<Value, String> {+ if self.conn.is_none() {+ self.drop_conn();+ return Err("the connection to the app was lost".into());+ }+ let line = self.request_line("control.pending", json!({}));+ let reply = self.roundtrip(&line).map_err(|e| self.explain(&e))?;+ let v: Value = serde_json::from_str(&reply).map_err(|e| format!("bad reply from the app: {e}"))?;+ outcome(&v).inspect_err(|_| self.drop_conn())+ }++ /// Wait up to `limit` for the outstanding request, asking `control.pending` now and then and+ /// saying on stderr how long it takes. An error: the connection, and so the reply, was lost.+ fn wait_outstanding(&mut self, limit: Duration) -> Result<Waited, String> {+ let start = Instant::now();+ let mut told = start;+ loop {+ let Some(o) = &self.outstanding else { return Ok(Waited::Nothing) };+ let what = o.what.clone();+ let r = self.ask_pending()?;+ if r.get("pending").is_none_or(Value::is_null) {+ self.outstanding = None;+ return Ok(Waited::Nothing);+ }+ if r.get("done").and_then(Value::as_bool) == Some(true) {+ self.outstanding = None;+ return Ok(Waited::Done(r.get("reply").cloned().unwrap_or(Value::Null)));+ }+ let waited = start.elapsed();+ if waited >= limit {+ return Ok(Waited::Running);+ }+ if told.elapsed() >= PROGRESS_EVERY {+ let secs = self.outstanding.as_ref().map_or(0, Outstanding::secs);+ eprintln!("solidcraft-mcp: {what} is still running in the app ({secs} s); waiting for it");+ told = Instant::now();+ }+ std::thread::sleep(self.waits.poll.min(limit.saturating_sub(waited)));+ }+ }++ /// The tool error for the outstanding request still running after its wait.+ fn still_running(&self, earlier: bool) -> String {+ let Some(o) = &self.outstanding else { return format!("{STILL_RUNNING} a request is still running in the app") };+ let effect = o.effect.map_or("it was not cancelled and may still change the design when it finishes", control_pending::Effect::when_done);+ let settle = self.waits.settle.as_secs();+ if earlier {+ format!(+ "{STILL_RUNNING} an earlier request, {}, is still running in the app ({} s; {effect}), so this call was not sent. Call the \+ `pending` tool to wait for its result, then send this call again",+ o.what,+ o.secs()+ )+ } else {+ format!(+ "{STILL_RUNNING} {} is still running in the app after {} s ({effect}); don't send it again. Call the `pending` tool to \+ wait for its result (up to {settle} s per call); other calls wait for it first",+ o.what,+ o.secs()+ )+ }+ }++ /// Before a new request: wait for one still running from an earlier call, keeping its end for+ /// `pending`. Still running after the wait: the new request is not sent.+ fn settle_earlier(&mut self) -> Result<(), String> {+ let Some(what) = self.outstanding.as_ref().map(|o| o.what.clone()) else { return Ok(()) };+ match self.wait_outstanding(self.waits.settle) {+ Ok(Waited::Done(reply)) => self.settled = Some(Settled::Finished { what, reply }),+ Ok(Waited::Nothing) => {}+ Ok(Waited::Running) => return Err(self.still_running(true)),+ // The connection was lost, and the earlier reply with it (`pending` says so): the new+ // request goes on a fresh connection.+ Err(_) => {}+ }+ Ok(())+ }++ /// `control.pending` for the bridge: the end of the request still running from an earlier+ /// call, waiting for it up to the settle wait. Never sent on a fresh connection, which has+ /// nothing pending.+ fn pending_status(&mut self) -> Result<Value, String> {+ if let Some(s) = self.settled.take() {+ return Ok(match s {+ Settled::Finished { what, reply } => json!({"pending": what, "done": true, "reply": reply}),+ Settled::Lost { what } => json!({"pending": what, "lost": true}),+ });+ }+ let Some(what) = self.outstanding.as_ref().map(|o| o.what.clone()) else { return Ok(json!({"pending": null})) };+ match self.wait_outstanding(self.waits.settle) {+ Ok(Waited::Done(reply)) => Ok(json!({"pending": what, "done": true, "reply": reply})),+ Ok(Waited::Nothing) => Ok(json!({"pending": null})),+ Ok(Waited::Running) => Ok(json!({"pending": what, "done": false, "running_s": self.outstanding.as_ref().map_or(0, Outstanding::secs)})),+ Err(_) => {+ self.settled = None;+ Ok(json!({"pending": what, "lost": true}))+ }+ }+ }++ fn call_once(&mut self, method: &str, params: Value, retry_busy: bool) -> Result<Value, String> {+ // The app answers `control.running` at once, even behind a request still running: it is+ // not held back for that one as other calls are.+ if method != "control.running" {+ self.settle_earlier()?;+ }+ let what = control_pending::describe(method, ¶ms);+ let effect = control_pending::effect(method, ¶ms);+ let again = retry_busy.then(|| params.clone());+ let sent = Instant::now();+ let line = self.request_line(method, params);let reply = if method == "engine.batch" {self.send_batch(&line)} else {@@ -189,11 +397,41 @@ impl Backend for Remote {}.map_err(|e| self.explain(&e))?;let v: Value = serde_json::from_str(&reply).map_err(|e| format!("bad reply from the app: {e}"))?;- if v.get("ok").and_then(Value::as_bool) == Some(true) {- Ok(v.get("result").cloned().unwrap_or(Value::Null))- } else {- Err(v.get("error").and_then(Value::as_str).unwrap_or("error").to_string())+ // Timed out in the app, still running (#1618): wait for its result on this connection.+ if v.get("running").and_then(Value::as_bool) == Some(true) {+ self.outstanding = Some(Outstanding { what: what.clone(), effect: Some(effect), since: sent });+ eprintln!(+ "solidcraft-mcp: {what} is still running in the app after {} s; waiting up to {} s more for it",+ sent.elapsed().as_secs(),+ self.waits.pending.as_secs()+ );+ return match self.wait_outstanding(self.waits.pending)? {+ Waited::Done(reply) => outcome(&reply),+ Waited::Nothing => {+ Err(format!("{what} timed out in the app, which kept no result for it: inspect the design before sending it again"))+ }+ Waited::Running => Err(self.still_running(false)),+ };+ }+ // Refused unrun behind a request this bridge did not know of: wait for that one, then+ // send this one once more.+ if v.get("busy").and_then(Value::as_bool) == Some(true)+ && let Some(params) = again+ {+ self.outstanding = Some(Outstanding { what: "an earlier request".into(), effect: None, since: Instant::now() });+ self.settle_earlier()?;+ return self.call_once(method, params, false);+ }+ outcome(&v)+ }+}++impl Backend for Remote {+ fn call(&mut self, method: &str, params: Value) -> Result<Value, String> {+ if method == "control.pending" {+ return self.pending_status();}+ self.call_once(method, params, true)}fn has_ui(&self) -> bool {true@@ -301,8 +539,10 @@ impl Backend for Headless {}))}"ui.screenshot" => Err("no window in headless mode; use ui.render".into()),- // Calls run here one at a time: none is running while this one is asked.+ // Calls run here one at a time: none is running while this one is asked, and nothing+ // is ever left running."control.running" => Ok(json!({"running": []})),+ "control.pending" => Ok(json!({"pending": null})),other => Err(format!("unknown method `{other}`")),}}diff --git a/crates/mcp/src/server.rs b/crates/mcp/src/server.rsindex adfe1567a6..a40c00f72f 100644--- a/crates/mcp/src/server.rs+++ b/crates/mcp/src/server.rs@@ -31,8 +31,9 @@ and degrees in expressions (internally radians), Z is up. Model like this: `sketand dimension (`sketch.dimension {entities, value}`; values may name parameters), `sketch.finish`, then features \(`solid.extrude {distance, operation?: new|join|cut|intersect}`, `solid.revolve`, `solid.fillet {edges: [[x,y,z] point on \edge], radius}`, `solid.chamfer`, patterns, mirror, primitives). Use `batch` for several steps at once, \-`list_commands` for ids and parameter docs, `describe_command` for a command's schemas, `inspect_design` / `measure` to verify, `body_topology` to find edge points, \-`set_parameter` to drive the design and `screenshot` to look at it.";+`list_commands` for ids and parameter docs, `describe_command` for a command's schemas, `inspect_design` / `measure` to verify, \+`body_topology` to find edge points, `set_parameter` to drive the design and `screenshot` to look at it. A call whose error \+starts `still running:` was not cancelled: don't send it again; `pending` waits for its result.";pub struct Server {backend: Box<dyn Backend>,diff --git a/crates/mcp/src/tests.rs b/crates/mcp/src/tests.rsindex dd664b40f3..3d82bfc116 100644--- a/crates/mcp/src/tests.rs+++ b/crates/mcp/src/tests.rs@@ -1523,7 +1523,7 @@ fn batch_reports_a_failed_engine_batch_like_before() {assert!(is_error);assert_eq!(body,- json!({"ok": false, "completed": 1, "failed": {"index": 1, "command": "a.two", "error": "boom"}, "rolled_back": true, "undone": 1, "results": [{"x": 1}]})+ json!({"ok": false, "completed": 1, "failed": {"index": 1, "command": "a.two", "error": "boom"}, "rolled_back": true, "undone": 1, "applied": [], "not_run": [], "results": [{"x": 1}]}));}@@ -1707,7 +1707,9 @@ fn tool_annotations_tell_the_whole_truth() {for name in ["execute", "batch", "save", "export", "open", "screenshot"] {assert_eq!(hints(name), (false, true, true), "{name}");}- for name in ["list_commands", "describe_command", "inspect_design", "measure", "body_topology", "crash_reports", "skill_reference", "running"] {+ for name in+ ["list_commands", "describe_command", "inspect_design", "measure", "body_topology", "crash_reports", "skill_reference", "running", "pending"]+ {assert_eq!(hints(name), (true, false, false), "{name}");}assert_eq!(hints("new_design"), (false, true, false));@@ -1776,6 +1778,319 @@ fn batch_reports_timings_and_profile() {assert!(body["timings"][0].get("profile").is_none(), "{body}");}+/// A fake app on a loopback port that answers every request line with `answer(request)`. The+/// shared state counts connections and records each request's method and command.+#[allow(clippy::type_complexity)]+fn scripted_app(answer: impl Fn(&Value) -> Value + Send + Sync + 'static) -> (String, std::sync::Arc<std::sync::Mutex<(usize, Vec<String>)>>) {+ use std::io::{BufRead, Write};+ let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();+ let addr = listener.local_addr().unwrap().to_string();+ let seen = std::sync::Arc::new(std::sync::Mutex::new((0usize, Vec::<String>::new())));+ let log = seen.clone();+ let answer = std::sync::Arc::new(answer);+ std::thread::spawn(move || {+ for stream in listener.incoming().flatten() {+ log.lock().unwrap().0 += 1;+ let (log, answer) = (log.clone(), answer.clone());+ std::thread::spawn(move || {+ let mut out = stream.try_clone().unwrap();+ let mut r = std::io::BufReader::new(stream);+ let mut line = String::new();+ while r.read_line(&mut line).is_ok_and(|n| n > 0) {+ let req: Value = serde_json::from_str(&line).unwrap();+ let what = match req["params"]["command"].as_str() {+ Some(c) => format!("{} {c}", req["method"].as_str().unwrap_or("")),+ None => req["method"].as_str().unwrap_or("").to_string(),+ };+ log.lock().unwrap().1.push(what);+ let mut reply = answer(&req);+ reply["id"] = req["id"].clone();+ if writeln!(out, "{reply}").is_err() {+ return;+ }+ line.clear();+ }+ });+ }+ });+ (addr, seen)+}++fn quick_waits(pending_ms: u64, settle_ms: u64) -> crate::backend::Waits {+ use std::time::Duration;+ crate::backend::Waits { pending: Duration::from_millis(pending_ms), settle: Duration::from_millis(settle_ms), poll: Duration::from_millis(5) }+}++fn running() -> Value {+ json!({"ok": false, "running": true, "error": "timeout: still running in the app"})+}++/// #1618 over MCP: a request the app says is still running is waited for on the same+/// connection (asking `control.pending`), and the call returns its real result.+#[test]+fn a_timed_out_request_is_waited_for_and_returns_its_result() {+ use crate::backend::Backend;+ use std::sync::atomic::{AtomicUsize, Ordering};+ let polls = AtomicUsize::new(0);+ let (addr, seen) = scripted_app(move |req| match req["method"].as_str() {+ Some("engine.execute") => running(),+ Some("control.pending") if polls.fetch_add(1, Ordering::SeqCst) < 2 => {+ json!({"ok": true, "result": {"pending": 1, "method": "engine.execute", "done": false}})+ }+ Some("control.pending") => {+ json!({"ok": true, "result": {"pending": 1, "method": "engine.execute", "done": true, "reply": {"ok": true, "result": {"filleted": true}}}})+ }+ _ => json!({"ok": true, "result": null}),+ });+ let mut remote = crate::Remote::connect(&addr).unwrap();+ remote.set_waits(quick_waits(5000, 1000));+ let r = remote.call("engine.execute", json!({"command": "solid.fillet"})).unwrap();+ assert_eq!(r, json!({"filleted": true}));+ let (connections, methods) = seen.lock().unwrap().clone();+ assert_eq!(connections, 1, "the reply waits on the connection: it is kept");+ assert_eq!(methods, ["engine.execute solid.fillet", "control.pending", "control.pending", "control.pending"]);+ // Nothing is outstanding any more.+ assert_eq!(remote.call("control.pending", json!({})).unwrap(), json!({"pending": null}));+}++/// #3654 with #1618: `control.running` is sent at once while a request still runs, not held+/// back behind it as other calls are, and asking it leaves that request outstanding.+#[test]+fn running_is_asked_at_once_behind_a_request_still_running() {+ use crate::backend::{Backend, STILL_RUNNING};+ let (addr, seen) = scripted_app(|req| match req["method"].as_str() {+ Some("engine.execute") => running(),+ Some("control.pending") => json!({"ok": true, "result": {"pending": 1, "method": "engine.execute", "done": false}}),+ Some("control.running") => json!({"ok": true, "result": {"running": [{"id": 1, "method": "engine.execute", "self": true}]}}),+ _ => json!({"ok": true, "result": "ran"}),+ });+ let mut remote = crate::Remote::connect(&addr).unwrap();+ remote.set_waits(quick_waits(20, 20));+ assert!(remote.call("engine.execute", json!({"command": "solid.fillet"})).unwrap_err().starts_with(STILL_RUNNING));+ std::mem::take(&mut seen.lock().unwrap().1);+ let r = crate::call_tool(&mut remote, "running", &json!({}));+ assert_ne!(r["isError"], true, "{r}");+ assert_eq!(seen.lock().unwrap().1, ["control.running"], "not behind the request still running");+ let e = remote.call("document.inspect", json!({})).unwrap_err();+ assert!(e.starts_with(STILL_RUNNING) && e.contains("earlier request"), "still outstanding: {e}");+}++/// A request still running after the wait is left to the `pending` tool: the error says so+/// (and that it will still apply, or only write its file), later calls are not sent behind it, and `pending` returns+/// its result once it lands, on the same connection.+#[test]+fn a_request_still_running_is_left_to_the_pending_tool() {+ use crate::backend::{Backend, STILL_RUNNING};+ use std::sync::atomic::{AtomicBool, Ordering};+ let done = std::sync::Arc::new(AtomicBool::new(false));+ let finished = done.clone();+ let (addr, seen) = scripted_app(move |req| match req["method"].as_str() {+ Some("engine.execute") if req["params"]["command"] != "inspect.measure" => running(),+ Some("control.pending") if finished.load(Ordering::SeqCst) => {+ json!({"ok": true, "result": {"pending": 1, "method": "engine.execute", "done": true, "reply": {"ok": true, "result": {"r": 1}}}})+ }+ Some("control.pending") => json!({"ok": true, "result": {"pending": 1, "method": "engine.execute", "done": false}}),+ _ => json!({"ok": true, "result": "ran"}),+ });+ let mut remote = crate::Remote::connect(&addr).unwrap();+ remote.set_waits(quick_waits(60, 60));+ let e = remote.call("engine.execute", json!({"command": "solid.fillet"})).unwrap_err();+ assert!(e.starts_with(STILL_RUNNING) && e.contains("solid.fillet") && e.contains("will still apply") && e.contains("`pending`"), "{e}");+ // Not sent behind it.+ let e = remote.call("document.inspect", json!({})).unwrap_err();+ assert!(e.starts_with(STILL_RUNNING) && e.contains("earlier request") && e.contains("not sent"), "{e}");+ assert!(!seen.lock().unwrap().1.iter().any(|m| m == "document.inspect"), "{:?}", seen.lock().unwrap().1);+ // `pending` while it still runs.+ let r = crate::call_tool(&mut remote, "pending", &json!({}));+ assert_ne!(r["isError"], true, "{r}");+ let body: Value = serde_json::from_str(r["content"][0]["text"].as_str().unwrap()).unwrap();+ assert_eq!(body["done"], false, "{body}");+ // It lands: `pending` returns its own result.+ done.store(true, Ordering::SeqCst);+ let r = crate::call_tool(&mut remote, "pending", &json!({}));+ let body: Value = serde_json::from_str(r["content"][0]["text"].as_str().unwrap()).unwrap();+ assert_eq!((&body["done"], &body["result"]), (&json!(true), &json!({"r": 1})), "{body}");+ assert_eq!(remote.call("document.inspect", json!({})).unwrap(), "ran");++ // Waited out by a later call instead: that call runs, and `pending` still has the result.+ done.store(false, Ordering::SeqCst);+ assert!(remote.call("engine.execute", json!({"command": "solid.chamfer"})).is_err());+ done.store(true, Ordering::SeqCst);+ assert_eq!(remote.call("engine.execute", json!({"command": "inspect.measure"})).unwrap(), "ran");+ let r = crate::call_tool(&mut remote, "pending", &json!({}));+ let body: Value = serde_json::from_str(r["content"][0]["text"].as_str().unwrap()).unwrap();+ assert_eq!((&body["done"], &body["result"]), (&json!(true), &json!({"r": 1})), "{body}");+ assert_eq!(seen.lock().unwrap().0, 1, "one connection throughout");++ // A request that only reads is not said to apply.+ done.store(false, Ordering::SeqCst);+ let e = remote.call("engine.execute", json!({"command": "sketch.inspect"})).unwrap_err();+ assert!(e.contains("only reads") && !e.contains("will still apply"), "{e}");++ // An export only writes its file (#1989): it is not said to apply either.+ let mut other = crate::Remote::connect(&addr).unwrap();+ other.set_waits(quick_waits(60, 60));+ let e = other.call("engine.execute", json!({"command": "file.export", "params": {"path": "/tmp/wall.step"}})).unwrap_err();+ assert!(e.starts_with(STILL_RUNNING) && e.contains("will still write the file") && !e.contains("apply"), "{e}");+ let e = other.call("document.inspect", json!({})).unwrap_err();+ assert!(e.contains("earlier request") && e.contains("will still write the file"), "{e}");+}++/// The headless session never leaves a request running.+#[test]+fn pending_is_empty_headless() {+ let mut s = server();+ assert_eq!(tool(&mut s, "pending", json!({}))["pending"], Value::Null);+}++/// A backend for the per-step batch path: `fail` maps commands to their errors, and+/// `edit.restore_checkpoint` works or not.+struct Stub {+ calls: Vec<(String, Value)>,+ fail: Vec<(&'static str, String)>,+ restore_ok: bool,+}++impl crate::backend::Backend for Stub {+ fn call(&mut self, method: &str, params: Value) -> Result<Value, String> {+ self.calls.push((method.to_string(), params.clone()));+ match (method, params["command"].as_str()) {+ ("engine.execute", Some("edit.checkpoint")) => Ok(json!({"checkpoint": 7})),+ ("engine.execute", Some("edit.restore_checkpoint")) if self.restore_ok => Ok(json!({})),+ ("engine.execute", Some("edit.restore_checkpoint")) => Err("busy: request 3 is still running".into()),+ ("engine.execute", Some(c)) => match self.fail.iter().find(|(f, _)| *f == c) {+ Some((_, e)) => Err(e.clone()),+ None => Ok(json!({"ran": c})),+ },+ (m, _) => Err(format!("unknown method `{m}`")),+ }+ }+ fn has_ui(&self) -> bool {+ true+ }+ fn describe(&self) -> String {+ "stub".into()+ }+}++fn stub_batch(fail: Vec<(&'static str, String)>, restore_ok: bool, rollback: bool) -> (Stub, Value) {+ let mut b = Stub { calls: Vec::new(), fail, restore_ok };+ let args = json!({"commands": [{"command": "a.one"}, {"command": "a.two"}, {"command": "a.three"}], "rollback": rollback});+ let r = crate::tools::call_tool(&mut b, "batch", &args);+ assert_eq!(r["isError"], true, "{r}");+ let body = serde_json::from_str(r["content"][0]["text"].as_str().unwrap()).unwrap();+ (b, body)+}++/// A failed batch says what really happened: `rolled_back` only when the checkpoint was restored,+/// which steps' changes are in the design (`applied`) and which were never sent (`not_run`). A+/// step still running in the app counts as applied unless the rollback took it back.+#[test]+fn a_failed_batch_reports_what_really_happened() {+ let still = format!("{} `engine.execute` (a.two) is still running in the app", crate::backend::STILL_RUNNING);+ // Still running, and the rollback could not restore the checkpoint.+ let (b, body) = stub_batch(vec![("a.two", still.clone())], false, true);+ assert_eq!((&body["rolled_back"], &body["undone"]), (&json!(false), &json!(0)), "{body}");+ assert_eq!((&body["applied"], &body["not_run"]), (&json!([0, 1]), &json!([2])), "{body}");+ assert_eq!(body["failed"]["still_running"], true, "{body}");+ assert!(!b.calls.iter().any(|(_, p)| p["command"] == "a.three"), "a step after the failure is never sent");+ // Still running, and the rollback (after the backend waited for it) restored the checkpoint.+ let (_, body) = stub_batch(vec![("a.two", still)], true, true);+ assert_eq!((&body["rolled_back"], &body["undone"]), (&json!(true), &json!(1)), "{body}");+ assert_eq!((&body["applied"], &body["not_run"]), (&json!([]), &json!([2])), "{body}");+ assert!(body["failed"].get("still_running").is_none(), "{body}");+ // An ordinary failure whose rollback failed.+ let (_, body) = stub_batch(vec![("a.two", "boom".into())], false, true);+ assert_eq!((&body["rolled_back"], &body["applied"]), (&json!(false), &json!([0])), "{body}");+ // No rollback asked for: nothing is restored, and the reply does not say it was.+ let (b, body) = stub_batch(vec![("a.two", "boom".into())], true, false);+ assert_eq!((&body["rolled_back"], &body["applied"], &body["not_run"]), (&json!(false), &json!([0]), &json!([2])), "{body}");+ assert!(!b.calls.iter().any(|(_, p)| p["command"] == "edit.restore_checkpoint"), "{:?}", b.calls);++ // The app's own engine.batch: its `rolled_back` is believed; an older app's is inferred.+ let reply = json!({"completed": 1, "results": [{"x": 1}], "failed": {"index": 1, "command": "a.two", "error": "boom"}, "undone": 0, "rolled_back": false});+ let (_, body, _) = recorded_batch(Ok(reply), json!({"commands": [{"command": "a.one"}, {"command": "a.two"}, {"command": "a.three"}]}));+ assert_eq!((&body["rolled_back"], &body["applied"], &body["not_run"]), (&json!(false), &json!([0]), &json!([2])), "{body}");+ let reply = json!({"completed": 1, "results": [{"x": 1}], "failed": {"index": 1, "command": "a.two", "error": "boom"}, "undone": 0});+ let (_, body, _) = recorded_batch(Ok(reply), json!({"commands": [{"command": "a.one"}, {"command": "a.two"}]}));+ assert_eq!(body["rolled_back"], false, "undone 0 of 1 completed: not rolled back: {body}");+ // A whole engine.batch still running in the app is not "may have run": `pending` gets it.+ let still = format!("{} `engine.batch` is still running in the app", crate::backend::STILL_RUNNING);+ let (b, body, is_error) = recorded_batch(Err(still), json!({"commands": [{"command": "a.one"}]}));+ assert!(is_error && body.as_str().is_some_and(|t| t.starts_with(crate::backend::STILL_RUNNING) && !t.contains("may have run")), "{body}");+ assert_eq!(methods(&b), ["engine.batch"]);+}++/// Batch steps may name the tools an agent knows: `list_commands` and `set_parameter` run as+/// engine.commands (filtered as the tool filters) and parameters.change; tools that can't be+/// steps fail the batch before anything is sent.+#[test]+fn batch_steps_may_name_tools() {+ let catalog = json!([{"id": "solid.box", "label": "Box", "tab": "SOLID", "panel": "CREATE"}, {"id": "sketch.line", "label": "Line", "tab": "SKETCH", "panel": "CREATE"}]);+ let reply = json!({"completed": 3, "results": [catalog, {"value": 40}, {"value": 20}], "undone": 0});+ let steps = json!([+ {"command": "list_commands", "params": {"filter": "box"}},+ {"command": "set_parameter", "params": {"name": "w", "value": 40}},+ {"command": "set_parameter", "params": {"name": "h", "expression": "w / 2", "unit": "mm"}},+ ]);+ let (b, body, is_error) = recorded_batch(Ok(reply), json!({"commands": steps}));+ assert!(!is_error, "{body}");+ assert_eq!(+ b.calls[0].1["commands"],+ json!([+ {"command": "engine.commands", "params": {}},+ {"command": "parameters.change", "params": {"name": "w", "expression": 40}},+ {"command": "parameters.change", "params": {"name": "h", "expression": "w / 2", "unit": "mm"}},+ ])+ );+ assert_eq!(body["results"][0], json!([{"id": "solid.box", "label": "Box", "tab": "SOLID", "panel": "CREATE"}]), "{body}");++ let (b, body, is_error) =+ recorded_batch(Ok(json!({})), json!({"commands": [{"command": "solid.box"}, {"command": "screenshot", "params": {"view": "iso"}}]}));+ assert!(is_error, "{body}");+ assert!(b.calls.is_empty(), "nothing is sent: {:?}", b.calls);+ assert_eq!((&body["failed"]["index"], &body["not_run"], &body["applied"]), (&json!(1), &json!([0, 1]), &json!([])), "{body}");+ assert!(body["failed"]["error"].as_str().is_some_and(|e| e.contains("screenshot")), "{body}");+ let (_, body, _) = recorded_batch(Ok(json!({})), json!({"commands": [{"command": "body_topology", "params": {"body": "Body1"}}]}));+ assert!(body["failed"]["error"].as_str().is_some_and(|e| e.contains("model.edges") && e.contains("model.faces")), "{body}");++ // Headless, step by step.+ let mut s = server();+ let r = tool(+ &mut s,+ "batch",+ json!({"commands": [+ {"command": "set_parameter", "params": {"name": "w", "value": "40 mm"}},+ {"command": "solid.box", "params": {"length": "w", "width": 10, "height": 10}},+ {"command": "list_commands", "params": {"filter": "solid.box"}},+ {"command": "execute", "params": {"command": "solid.sphere", "params": {"radius": 2, "center": [100, 0, 0]}}},+ {"command": "describe_command", "params": {"id": "solid.box"}},+ ]}),+ );+ assert_eq!(r["completed"], 5, "{r}");+ assert!(r["results"][4]["input"]["properties"].get("operation").is_some(), "{r}");+ let ids: Vec<&str> = r["results"][2].as_array().unwrap().iter().filter_map(|c| c["id"].as_str()).collect();+ assert!(!ids.is_empty() && ids.iter().all(|id| id.contains("solid.box")), "{ids:?}");+ assert!(volume(&mut s) > 4000.0);+}++/// An unknown argument is refused with the tool's real arguments listed.+#[test]+fn unknown_arguments_list_the_real_ones() {+ let mut s = server();+ for (tool_name, want) in [+ ("screenshot", &["view", "camera", "path", "width", "height", "source", "grid", "axes"][..]),+ ("inspect_design", &["measure", "sketches"][..]),+ ("body_topology", &["body"][..]),+ ] {+ let args = if tool_name == "body_topology" { json!({"body": "Body1", "nonsense": 3}) } else { json!({"nonsense": 3}) };+ let r = raw_tool(&mut s, tool_name, args);+ let msg = r["error"]["message"].as_str().unwrap_or_default();+ assert_eq!(r["error"]["code"], -32602, "{r}");+ assert!(msg.contains("unknown argument `nonsense`") && want.iter().all(|a| msg.contains(a)), "{tool_name}: {msg}");+ }+}+/// `describe_command` serves a converted command's schemas, and a headless session set to strict/// refuses a misspelt key through `execute` without touching the design.#[test]diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rsindex 6f21fd1206..231e2b67e3 100644--- a/crates/mcp/src/tools.rs+++ b/crates/mcp/src/tools.rs@@ -7,7 +7,7 @@ use serde_json::{Map, Value, json};use solidcraft_engine::io::vfs;use solidcraft_engine::timing;-use crate::backend::Backend;+use crate::backend::{Backend, STILL_RUNNING};/// Most commands in one `batch` call.const MAX_BATCH: usize = 10_000;@@ -106,10 +106,17 @@ pub fn tool_definitions() -> Vec<Value> {tool("batch","Run several commands",- "Run commands in order, stopping at the first error. Each step is {command, params}. On an error the steps \- already run are undone (unless rollback: false), so the batch is all-or-nothing; the reply names the failing \- step (index from 0), its error, and every result before it. The usual way to build a part: sketch, draw, \- dimension, finish, extrude, fillet… in one call.",+ "Run commands in order, stopping at the first error. Each step is {command, params}: an engine command id \+ (as list_commands lists them). A step may also name one of these tools with that tool's arguments as params, \+ and runs the engine command it stands for: set_parameter (parameters.change; `value` or `expression`), \+ list_commands (engine.commands, with `filter`), describe_command (engine.describe), execute ({command, params}), \+ measure (inspect.measure), \+ inspect_design (document.inspect), undo, redo, export, save, open, new_design, crash_reports; screenshot, \+ body_topology, batch and pending can't be steps. On an error the steps already run are undone (unless \+ 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.",obj(json!({"commands": {@@ -265,6 +272,16 @@ pub fn tool_definitions() -> Vec<Value> {obj(json!({}), &[]),Effect::ReadOnly,),+ tool(+ "pending",+ "Result of a running request",+ "Bridged to the app: the result of a request that was still running when its tool call returned (an error \+ starting \"still running:\"). Waits for it up to 60 s: then its own result (or error), or done: false while \+ it still runs (call again). pending: null when nothing is running. A request still running was not \+ cancelled: don't send it again; other calls wait for it before they are sent.",+ obj(json!({}), &[]),+ Effect::ReadOnly,+ ),tool("undo", "Undo", "Undo the last change to the design.", obj(json!({}), &[]), Effect::Edits),tool("redo", "Redo", "Redo the last undone change.", obj(json!({}), &[]), Effect::Edits),tool(@@ -350,7 +367,10 @@ pub(crate) fn check_arguments(name: &str, args: &Value) -> Result<(), String> {let props = schema["properties"].as_object();for (k, v) in a {let Some(p) = props.and_then(|p| p.get(k)) else {- return Err(format!("{name}: unknown argument `{k}`"));+ let valid: Vec<&str> = props.map(|p| p.keys().map(String::as_str).collect()).unwrap_or_default();+ let valid = if valid.is_empty() { "none".to_string() } else { valid.join(", ") };+ let k: String = k.chars().take(64).collect();+ return Err(format!("{name}: unknown argument `{k}`; its arguments are: {valid}"));};if v.is_null() {continue;@@ -475,12 +495,7 @@ fn dispatch(b: &mut dyn Backend, name: &str, a: &Map<String, Value>) -> Result<Vmatch name {"list_commands" => {let all = b.call("engine.commands", json!({}))?;- let Some(f) = str_arg(a, "filter").map(str::to_lowercase).filter(|f| !f.is_empty()) else { return Ok(all) };- let hit = |c: &Value| {- // Not "params": many docs name other commands (e.g. "usable in sketch.delete"), #269.- ["id", "label", "panel", "tab"].iter().any(|k| c.get(*k).and_then(Value::as_str).is_some_and(|s| s.to_lowercase().contains(&f)))- };- Ok(Value::Array(all.as_array().map(|v| v.iter().filter(|c| hit(c)).cloned().collect()).unwrap_or_default()))+ Ok(filter_commands(all, str_arg(a, "filter")))}"describe_command" => {let id = str_arg(a, "id").ok_or("`id` is required")?;@@ -511,6 +526,7 @@ fn dispatch(b: &mut dyn Backend, name: &str, a: &Map<String, Value>) -> Result<V}Ok(d)}+ "pending" => pending(b),"measure" => {if let Some(items) = a.get("items") {return exec(b, "inspect.measure", json!({ "items": items }));@@ -548,6 +564,114 @@ fn dispatch(b: &mut dyn Backend, name: &str, a: &Map<String, Value>) -> Result<V}}+/// The command catalog filtered by a case-insensitive substring of id, label, panel or tab+/// (`list_commands`; not the parameter docs, which name other commands, #269).+fn filter_commands(all: Value, filter: Option<&str>) -> Value {+ let Some(f) = filter.map(str::to_lowercase).filter(|f| !f.is_empty()) else { return all };+ let hit =+ |c: &Value| ["id", "label", "panel", "tab"].iter().any(|k| c.get(*k).and_then(Value::as_str).is_some_and(|s| s.to_lowercase().contains(&f)));+ Value::Array(all.as_array().map(|v| v.iter().filter(|c| hit(c)).cloned().collect()).unwrap_or_default())+}++/// `pending`: the end of a request still running when its call returned (bridged only; a+/// headless session runs every request to its end).+fn pending(b: &mut dyn Backend) -> Result<Value, String> {+ let p = b.call("control.pending", json!({}))?;+ let what = p.get("pending").cloned().unwrap_or(Value::Null);+ if what.is_null() {+ return Ok(json!({"pending": null, "note": "nothing is running"}));+ }+ let name = what.as_str().unwrap_or("the request").to_string();+ if p.get("lost").and_then(Value::as_bool) == Some(true) {+ return Err(format!(+ "the connection to the app was lost while {name} was running, and its result with it: inspect the design (inspect_design) \+ to see whether it applied before sending it again"+ ));+ }+ if p.get("done").and_then(Value::as_bool) == Some(true) {+ let reply = p.get("reply").cloned().unwrap_or(Value::Null);+ return match reply.get("ok").and_then(Value::as_bool) {+ Some(true) => Ok(json!({"pending": what, "done": true, "result": reply.get("result").cloned().unwrap_or(Value::Null)})),+ _ => Err(format!("{name} failed: {}", reply.get("error").and_then(Value::as_str).unwrap_or("no reply"))),+ };+ }+ Ok(json!({"pending": what, "done": false, "running_s": p.get("running_s"), "note": "still running: call pending again to keep waiting"}))+}++/// A `batch` step as the engine command it runs: an engine command as it is, or one of these+/// tools' names (an agent writes the tool it knows) with that tool's arguments as its params.+/// `Ok((command, params, filter))`: `filter` narrows a `list_commands` step's catalog; an empty+/// `command` means the step is an engine command already.+fn batch_step(step: &Value) -> Result<(String, Value, Option<String>), String> {+ let command = step.get("command").or_else(|| step.get("id")).and_then(Value::as_str).ok_or("missing `command`")?;+ let empty = Map::new();+ let params = step.get("params").cloned().filter(|p| !p.is_null()).unwrap_or(json!({}));+ let a = params.as_object().unwrap_or(&empty);+ let mapped = |c: &str, p: Value| Ok((c.to_string(), p, None));+ match command {+ "list_commands" => Ok(("engine.commands".into(), json!({}), str_arg(a, "filter").map(str::to_string))),+ "set_parameter" => {+ let mut p = pick(a, &["name", "unit", "comment"]);+ p["expression"] = parameter_value(a)?;+ mapped("parameters.change", p)+ }+ "describe_command" => mapped("engine.describe", json!({"command": str_arg(a, "id").ok_or("a `describe_command` step needs params {id}")?})),+ "execute" => {+ let inner = str_arg(a, "command").ok_or("an `execute` step needs params {command, params}")?;+ if !inner.contains('.') && TOOL_STEPS.contains(&inner) {+ return Err(format!("an `execute` step runs an engine command, not the `{inner}` tool"));+ }+ mapped(inner, a.get("params").cloned().filter(Value::is_object).unwrap_or(json!({})))+ }+ "measure" => match a.get("items") {+ Some(items) => mapped("inspect.measure", json!({"items": items})),+ None => mapped("inspect.measure", str_arg(a, "body").map_or(json!({}), |body| json!({"bodies": [body]}))),+ },+ "inspect_design" => mapped("document.inspect", json!({"measure": a.get("measure").and_then(Value::as_bool).unwrap_or(true)})),+ "undo" => mapped("edit.undo", json!({})),+ "redo" => mapped("edit.redo", json!({})),+ "export" => mapped("file.export", pick(a, &["path", "format", "bodies", "mesh_prefix", "effort", "velocity"])),+ "save" => mapped("file.save", pick(a, &["path", "format"])),+ "open" => mapped("doc.open", pick(a, &["path", "up", "names"])),+ "new_design" => mapped("file.new", pick(a, &["name"])),+ "crash_reports" => match a.get("id") {+ Some(_) => mapped("diagnostics.crash_report", pick(a, &["id"])),+ None => mapped("diagnostics.crash_reports", pick(a, &["limit"])),+ },+ "body_topology" => Err("`body_topology` is a tool, not a command: in a batch use model.edges {body} and model.faces {body}".into()),+ "screenshot" => Err("`screenshot` is a tool, not a command: call it after the batch".into()),+ "batch" => Err("batches don't nest: put the steps in this batch".into()),+ "pending" => Err("`pending` is a tool, not a command: call it on its own".into()),+ "running" => Err("`running` is a tool, not a command: call it on its own".into()),+ "skill_reference" => Err("`skill_reference` is a tool, not a command: call it on its own".into()),+ // An engine command: the step goes as it is.+ _ => Ok((String::new(), Value::Null, None)),+ }+}++/// The tool names a `batch` step may not be (or is mapped from): `execute` must not wrap them.+const TOOL_STEPS: &[&str] = &[+ "batch",+ "body_topology",+ "crash_reports",+ "describe_command",+ "execute",+ "export",+ "inspect_design",+ "list_commands",+ "measure",+ "new_design",+ "open",+ "pending",+ "redo",+ "running",+ "save",+ "screenshot",+ "set_parameter",+ "skill_reference",+ "undo",+];+/// `set_parameter`'s new value: `value` or `expression` (the parameters.change name), one of/// them, or both when they agree (`50` and `"50"` do).fn parameter_value(a: &Map<String, Value>) -> Result<Value, String> {@@ -585,8 +709,9 @@ impl Undo {}}- /// Go back; (whether the design is back as it was, the number of steps undone). A failed- /// rollback says so rather than reporting the flag the caller asked for (#3242).+ /// Go back: whether the design really is back where the batch started, and the number of+ /// steps undone. A failed rollback says so rather than reporting the flag the caller asked+ /// for (#3242).fn rollback(self, b: &mut dyn Backend, steps: usize) -> (bool, u64) {match self {Undo::Checkpoint(id) => match exec(b, "edit.restore_checkpoint", json!({"checkpoint": id})) {@@ -594,7 +719,7 @@ impl Undo {Err(_) => (false, 0),},Undo::Depth(before) => {- let after = undo_depth(b).unwrap_or(before);+ let Some(after) = undo_depth(b) else { return (false, 0) };let mut undone = 0u64;for _ in before..after {if exec(b, "edit.undo", json!({})).is_err() {@@ -602,7 +727,7 @@ impl Undo {}undone += 1;}- (undone == steps as u64, undone)+ (undone == after.saturating_sub(before), undone)}// Nothing remembered the design; only a first step that failed left nothing behind.Undo::None => (steps == 0, 0),@@ -630,6 +755,44 @@ fn batch(b: &mut dyn Backend, a: &Map<String, Value>) -> Value {let verbose = a.get("verbose").and_then(Value::as_bool).unwrap_or(true);let profile = a.get("profile").and_then(Value::as_bool).unwrap_or(false);let timed = profile || a.get("timings").and_then(Value::as_bool).unwrap_or(false);+ // Steps that name a tool run the engine command it stands for. One that can't be a step+ // fails the batch before anything is sent.+ let mut mapped: Vec<Value> = Vec::with_capacity(steps.len());+ let mut filters: Vec<(usize, String)> = Vec::new();+ for (i, step) in steps.iter().enumerate() {+ match batch_step(step) {+ Ok((command, _, _)) if command.is_empty() => mapped.push(step.clone()),+ Ok((command, params, filter)) => {+ if let Some(f) = filter {+ filters.push((i, f));+ }+ mapped.push(json!({"command": command, "params": params}));+ }+ // A step without a command fails where it stands, as before.+ Err(e) if e == "missing `command`" => mapped.push(step.clone()),+ Err(e) => {+ let command = step.get("command").or_else(|| step.get("id")).and_then(Value::as_str);+ let reply = json!({+ "ok": false,+ "completed": 0,+ "failed": {"index": i, "command": command, "error": e},+ "rolled_back": false,+ "undone": 0,+ "applied": [],+ "not_run": (0..steps.len()).collect::<Vec<_>>(),+ "results": [],+ "note": "nothing was run",+ });+ return text_result(&reply, true);+ }+ }+ }+ let steps = &mapped;+ // 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)),+ None => v,+ };// An app that runs batches itself answers the whole batch in one request, so one frame// (#743). One too long for a control line goes step by step: the app would refuse it unrun.// The margin covers the envelope and the `allow_paths` the backend adds.@@ -649,12 +812,15 @@ fn batch(b: &mut dyn Backend, a: &Map<String, Value>) -> Value {failed.insert("error".into(), Value::String(error));}}- return batch_reply(&r, rollback, verbose);+ return batch_reply(&r, steps.len(), rollback, verbose, &narrow);}// Older apps and the headless session, or the app wants the steps one by one.Err(e) if e.starts_with("unknown method") || e.starts_with("engine.batch unavailable") => {}- // Never sent: no app to send it to.- Err(e) if e.starts_with(crate::backend::NOT_RUNNING) => return text_result(&Value::String(e), true),+ // 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);+ }// 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");@@ -678,15 +844,33 @@ fn batch(b: &mut dyn Backend, a: &Map<String, Value>) -> Value {rows.push(took.to_json(i, command.unwrap_or_default()));}match r {- Ok(v) => results.push(if verbose { v } else { compact(v) }),+ Ok(v) => {+ let v = narrow(i, v);+ results.push(if verbose { v } else { compact(v) })+ }Err(e) => {- let (rolled_back, undone) = start.rollback(b, i);+ // A step still running in the app was not cancelled: the rollback first waits for+ // it (the backend does), so a restored checkpoint takes it back too.+ let running = e.starts_with(STILL_RUNNING);+ let (went_back, undone) = start.rollback(b, i);+ // Only a rollback asked for is reported as one.+ let rolled_back = rollback && went_back;+ let mut failed = json!({"index": i, "command": command, "error": e});+ // Applied: the steps before it, unless rolled back; and the step itself while it+ // still runs, as it will apply when it finishes.+ let mut applied: Vec<usize> = if rolled_back { Vec::new() } else { (0..i).collect() };+ if running && !rolled_back {+ failed["still_running"] = json!(true);+ applied.push(i);+ }let reply = json!({"ok": false,"completed": i,- "failed": {"index": i, "command": command, "error": e},+ "failed": failed,"rolled_back": rolled_back,"undone": undone,+ "applied": applied,+ "not_run": (i + 1..steps.len()).collect::<Vec<_>>(),"results": results,});return text_result(&with_timings(reply, timed, rows, clock.ms()), true);@@ -708,24 +892,35 @@ fn with_timings(mut reply: Value, timed: bool, rows: Vec<Value>, 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, rollback: bool, verbose: bool) -> Value {- let results: Vec<Value> =- r["results"].as_array().cloned().unwrap_or_default().into_iter().map(|v| if verbose { v } else { compact(v) }).collect();+fn batch_reply(r: &Value, len: usize, rollback: bool, verbose: bool, narrow: &dyn Fn(usize, Value) -> Value) -> Value {+ let results: Vec<Value> = r["results"]+ .as_array()+ .cloned()+ .unwrap_or_default()+ .into_iter()+ .enumerate()+ .map(|(i, v)| narrow(i, v))+ .map(|v| if verbose { v } else { compact(v) })+ .collect();let (mut reply, error) = match r.get("failed").filter(|f| !f.is_null()) {None => (json!({"ok": true, "completed": results.len(), "results": results}), false),Some(failed) => {- // `rolled_back` tells whether the design went back, not whether a rollback was- // asked for (#3242): the app answers with its own `rolled_back`; an app that- // predates that field and undid none of the steps it had completed did not go back.- let undone = r["undone"].as_u64().unwrap_or(0);- let went_back = r.get("rolled_back").and_then(Value::as_bool).unwrap_or(undone > 0 || r["completed"].as_u64() == Some(0));+ let completed = r["completed"].as_u64().map_or(results.len(), |c| c as usize).min(len);+ // `rolled_back` tells whether the design went back, not whether a rollback was asked+ // for (#3242): an app that says so is believed; an older one went back when it undid+ // every completed step (none completed: nothing to take back).+ let went_back = r.get("rolled_back").and_then(Value::as_bool).unwrap_or_else(|| r["undone"].as_u64() == Some(completed as u64));+ let rolled_back = rollback && went_back;+ let applied: Vec<usize> = if rolled_back { Vec::new() } else { (0..completed).collect() };(json!({"ok": false,"completed": r["completed"],"failed": failed,- "rolled_back": rollback && went_back,+ "rolled_back": rolled_back,"undone": r["undone"],+ "applied": applied,+ "not_run": (completed + 1..len).collect::<Vec<_>>(),"results": results,}),true,diff --git a/docs/control-protocol.md b/docs/control-protocol.mdindex def9c3b1be..fb059e4e64 100644--- a/docs/control-protocol.md+++ b/docs/control-protocol.md@@ -75,13 +75,20 @@ answered within 60 seconds (3600 seconds for `engine.batch`) is replied to with`{"ok": false, "running": true, "error": "timeout: … is still running …"}`. The same 16 MiB linelimit applies to the MCP server.-A timed-out request has not failed: it is still running in the app and will still apply (a long-fillet, say), so don't simply send it again. The connection keeps its reply (#1618). Ask for it+A timed-out request has not failed: it is still running in the app, and a change still applies+when it finishes (a long fillet, say), so don't simply send it again. The timeout's text says+what it still does: a request that only reads (`ui.inspect`, `document.inspect`, an inspection+command) "only reads: nothing changes"; one that only writes a file (`file.export`,+`file.save`, `file.save_as`, `file.save_mesh`, another export given a `path`, `ui.render`, or+`ui.screenshot` with a `path`) "will still write the file when it finishes" and leaves the design+as it is; any other request "will still apply when it finishes". The connection keeps its reply (#1618). Ask for itwith `control.pending`: `{"pending": <id>, "method": …, "done": false}` while it runs, then`{"pending": <id>, "method": …, "done": true, "reply": {…}}` (its own reply, once), and`{"pending": null}` when nothing is outstanding. Until it lands, any other request on thatconnection is refused at once with `{"ok": false, "busy": true, "error": "busy: …"}` and not-run, so nothing is queued to apply unseen behind it.+run, so nothing is queued to apply unseen behind it. `control.pending` belongs to the+connection: a new connection has nothing pending. The bridged MCP server does this itself+([mcp.md](mcp.md#long-running-requests)).`control.pending` answers only for its own connection. `control.running` answers for the wholeapp, the same on every connection, at once (it never waits behind a running request, and a@@ -215,7 +222,7 @@ labels; `prefs:measure_axis_distances` identifies the checkbox.| `ui.sketchToScreen` | `points`: `[[x, y]…]` in active-sketch coordinates | their screen points (null when behind the camera) || `ui.dialogInput` | `index` | what clicking an input's Select chip does: picks go to that input || `ui.at` | `world: [x,y,z]` \| `sketch: [x,y]` \| `plane: "XY"` \| `axis: "Z"` \| `dimension: "d1"` (its value text) \| `handle: "arrow"` (a manipulator handle, see `scenario::publish_handle`) | the screen point (a scenario step's target; see `crates/ui-egui/src/scenario.rs`) |-| `ui.handles` | `prefix?` | the handles drawn last frame, `[{name, x, y}]`: toolbar buttons and drop-down items `toolbar:<command id>` (the button alone: `button:<command id>`; a drop-down row: `dropdown:<command id>`, highlighted `dropdown_hot:<command id>`, its pin `dropdown_pin:<command id>`; Customize Toolbar's check boxes `customize:<command id>`), ribbon tabs `tab:<name>` (MODEL, SURFACE, ASSEMBLE, INSERT, INSPECT, MANAGE, VIEW, SHEET METAL; contextual SKETCH; workspace RENDER), panel labels `panel:<tab>:<panel>` (also `ribbon:section:<TAB>:<SECTION>`), document overflow list `tab:overflow`, workspace column `ribbon:workspace`, command-search launcher `ribbon:search`, browser rows `row:<label>` and fold arrows `fold:<label>`, manipulator handles; signed-axis tips `axis_view:z`, `axis_view:-y`; optional cube facets `navigation_cube:top`, `navigation_cube:top_front_right`, controls `navigation_cube:control:home` (and other actions), plus signed-axis aliases for visible cube faces; Preferences navigator picker `prefs:navigator`, options `prefs:navigator:Signed axes` and `prefs:navigator:Cube`; in the Motion Study dialog, where the chart puts its first and last step `motion:chart_start` and `motion:chart_end`, the Check collisions button `motion:check` and each collision found `motion:collision:<n>` |+| `ui.handles` | `prefix?` | the handles drawn last frame, `[{name, x, y}]`: toolbar buttons and drop-down items `toolbar:<command id>` (the button alone: `button:<command id>`; a drop-down row: `dropdown:<command id>`, highlighted `dropdown_hot:<command id>`, its pin `dropdown_pin:<command id>`; Customize Toolbar's check boxes `customize:<command id>`), ribbon tabs `tab:<name>` (MODEL, SURFACE, ASSEMBLE, INSERT, INSPECT, MANAGE, VIEW; contextual SKETCH and SHEET METAL; workspace RENDER), panel labels `panel:<tab>:<panel>` (also `ribbon:section:<TAB>:<SECTION>`), document overflow list `tab:overflow`, workspace column `ribbon:workspace`, command-search launcher `ribbon:search`, browser rows `row:<label>` and fold arrows `fold:<label>`, manipulator handles; signed-axis tips `axis_view:z`, `axis_view:-y`; optional cube facets `navigation_cube:top`, `navigation_cube:top_front_right`, controls `navigation_cube:control:home` (and other actions), plus signed-axis aliases for visible cube faces; Preferences navigator picker `prefs:navigator`, options `prefs:navigator:Signed axes` and `prefs:navigator:Cube`; in the Motion Study dialog, where the chart puts its first and last step `motion:chart_start` and `motion:chart_end`, the Check collisions button `motion:check` and each collision found `motion:collision:<n>` || `ui.editFeature` | `feature` (id or name) | what double-clicking a timeline item does: rolls back to it and opens its dialog filled in (sketches open in sketch mode) || `ui.scroll` | `x`, `y`, `delta?` | wheel zoom at the cursor || `ui.key` | `key` (egui key name, `Enter`, `Escape`…), `cmd?`, `ctrl?`, `shift?`, `alt?`, `pressed?` | By default, press and release, then release modifiers. With `pressed: true` or `false`, send only that edge; modifiers remain as given. `cmd` retains the legacy primary-modifier alias unless `ctrl` is explicit: `cmd:true, ctrl:false` sends physical Command, and both true sends Control+Command. `ui.move` can change modifiers between edges. |diff --git a/docs/mcp.md b/docs/mcp.mdindex 0eb2784b57..33c6bfa813 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -126,8 +126,8 @@ file dialogs are never limited.Each tool says what it may do, for clients that ask before running tools (or auto-approve onthese hints). `list_commands`, `describe_command`, `inspect_design`, `measure`, `body_topology`,-`skill_reference` and `crash_reports` are read-only. `set_parameter`, `undo` and `redo` change the design undoably.-`new_design` replaces it (destructive). `execute`, `batch`, `open`, `save`, `export` and+`skill_reference`, `crash_reports`, `pending` and `running` are read-only. `set_parameter`, `undo` and `redo`+change the design undoably. `new_design` replaces it (destructive). `execute`, `batch`, `open`, `save`, `export` and`screenshot` (whose `path` writes a file) can read, write, overwrite or delete files: they arenot read-only, `destructiveHint` and `openWorldHint` are true.@@ -205,7 +205,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 (`solid.box`, `solid.extrude` and `engine.describe` so far), 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?` (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`) and every result before it. `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`. |+| `batch` | `commands: [{command, params}]`, `rollback?` (default true), `verbose?` (default true), `timings?`, `profile?` (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`. || `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?` | Volume (mm³), area (mm²), centre of mass, bbox and topology counts per body, with totals. With `items` (one or two selections as `execute` takes them: `face`, `edge`, `vertex`, `sketch_curve`, `profile`), the picked geometry instead: 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`). |@@ -213,6 +213,7 @@ The `skill_reference` tool returns these documents from the copies built into So| `screenshot` | `view?` (iso, top, front, back, bottom, left, right, home, fit, or a named view saved with `view.save`), `camera?` (`{target, yaw, pitch, distance, fov?}`, as `view.apply`), `path?`, `width?`, `height?`, `source?` (window, model), `grid?`, `axes?` | A PNG image content block. Headless: a render with the viewport's pipelines on a headless GPU device (see `solidcraft-cli gpu`; with no adapter, the CPU rasterizer, without analysis colours), fitted to the model, or from the named view or camera; the reply's `renderer` says which (`gpu`, `gpu-software`, `cpu`, with a `warning` for `cpu`). Bridged: the app window (default) or a model render with the app's camera; a named view or camera moves the app's viewport there first (`execute` `view.apply` does the same without a screenshot). `grid: false` and `axes: false` leave the ground grid (it lies on Z 0 and cuts through a part that straddles it) and the origin's axes out of a model render; axes hidden with `browser.visibility` stay out whatever `axes` says. Bridged, a screenshot that gives `grid` or `axes` is a model render, which follows the app's Grid and Origin switches for what it does not give; `source: "window"` with either is an error. A window that is minimised or on another macOS Space presents no frame: with no `source` the reply is a model render and says so (`fallback`); `source: "window"` is an error saying why, at once. Agents that don't need the app's chrome can ask for `source: "model"`. || `export` | `path`, `format?` (step, 3mf, 3mf-tagged, stl, stla, obj, urdf), `bodies?`, `mesh_prefix?`, `effort?`, `velocity?` | STEP, 3MF or mesh export; URDF writes the whole assembly with its meshes next to it (`docs/urdf.md`). || `undo`, `redo` | — | Undo / redo one change. |+| `pending` | — | Bridged: the result of a request that was still running when its call returned (an error starting `still running:`), waiting up to 60 s for it; `done: false` while it runs (call again), `pending: null` when nothing runs. See [Long-running requests](#long-running-requests). || `crash_reports` | `id?`, `limit?` | The crash reports on this computer, newest first; with `id`, the whole report (backtrace, command, recent commands, `design_path`/`replay_path`). See [crash-reports.md](crash-reports.md). || `skill_reference` | `skill`, `file?` (default `reference.md`) | Read a bundled skill document. Skills: `solidcraft-modeling`, `solidcraft-mechanisms`, `solidcraft-editing`, `solidcraft-checking`. || `running` | - | What the app is running or has queued, for every client (`control.running`, see [control-protocol.md](control-protocol.md#limits)): each request's connection and id, method, command id or a batch's step count, `running_s` and `queued`, never its parameters. Answers at once while the app is busy: ask it when a call timed out before sending a change again. Headless: always `{"running": []}`. |@@ -247,8 +248,36 @@ Resources: `solidcraft://design` (inspect JSON with measurements) and `solidcraf(the catalog).Errors: an unknown tool or arguments that don't match the tool's schema are JSON-RPC-`-32602` errors; an engine failure (bad command parameters, a feature that fails) is a tool-result with `isError: true` and the engine's message, which the model can read and correct.+`-32602` errors (an unknown argument's error lists the tool's arguments); an engine failure+(bad command parameters, a feature that fails) is a tool result with `isError: true` and the+engine's message, which the model can read and correct.++### Long-running requests++The app answers a control request that runs longer than 60 seconds (a big fillet, say) with+"still running" ([control-protocol.md](control-protocol.md#limits)); it has not failed, and was+not cancelled. The bridged server then keeps the connection, where the reply will come, and+asks the app (`control.pending`) every half second for up to 240 seconds more, saying on stderr+how long it waits; when the request finishes, the tool call returns its real result. If it still+runs after that, the tool call fails with an error starting `still running:` that names the+request and says what it still does: it will still apply when it finishes, or will still write+the file (an export or a save: the design does not change), or only reads (nothing changes). Don't+send it again: call the `pending` tool, which waits up to 60 seconds for its result each time.+Any other tool call first waits up to 60 seconds for it too, and is not sent while it still runs+(so nothing is queued to apply unseen behind it); a request that finishes in that wait keeps its+result for `pending`. If the connection to the app is lost meanwhile, the result is lost with it,+and `pending` says so: inspect the design before sending a change again.++So a single tool call may block for up to 300 seconds (the app's 60 s wait plus 240 s of polling)+before it returns `still running:`, and a call made while an earlier request still runs for up to+60 seconds more. An MCP client needs a per-call timeout above that (say 330 s) to see that error;+a client that gives up sooner only sees its own timeout, though the request goes on running in the+app: then call `pending` (or `inspect_design`) before sending anything again.++A `batch` step that is still running stops the batch like a failure. Its rollback first waits for+the step (as above), so a restored checkpoint takes the step back too; if it still runs, the+reply says `rolled_back: false`, marks the step `still_running` and lists it in `applied`, as it+will apply when it finishes.`batch` rollback goes back to an engine checkpoint (`edit.checkpoint`) taken before the firststep: the design, the active sketch and the undo history are restored exactly as they were,