Skip to content

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.rs
index 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::fro
struct 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, &params);
+ let effect = control_pending::effect(&method, &params);
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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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, &params);
+ let effect = control_pending::effect(method, &params);
+ 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.rs
index 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: `sket
and 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.rs
index 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.rs
index 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<V
match 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.md
index 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 line
limit 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 it
with `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 that
connection 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 whole
app, 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.md
index 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 on
these 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 are
not 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 first
step: the design, the active sketch and the undo history are restored exactly as they were,