From 6c6ffe480210dc286be4ed2d347f2850994e0126 Mon Sep 17 00:00:00 2001 From: SS-EN <84559909+SS-EN@users.noreply.github.com> Date: Sat, 24 Oct 2026 02:41:41 +0000 Subject: [PATCH] MCP: wait out long requests, honest batch outcomes, batch tool aliases (#2901) Rebased onto main as one commit (was 120d26f7, df488f9a, db9d1073 plus merges of main). - A request the app reports as still running (#1618) is waited for on the same connection through `control.pending`; past the wait the error says it was not cancelled and will still apply (or only write its file), later calls are not sent behind it, and the new read-only `pending` tool returns its result once it lands. - A failed batch says what really happened: `rolled_back` only when the design is back where the batch started (as #3288 / #3242 on main: the app's `rolled_back` is believed; for an older app, every completed step undone; only a rollback asked for is reported as one), plus `applied`, `not_run` and `failed.still_running`. - A batch step may name a tool (set_parameter, list_commands, describe_command, execute, measure, inspect_design, undo, redo, export, save, open, new_design, crash_reports); screenshot, body_topology, batch and pending are refused before anything is sent. Co-authored-by: Claude Opus 5.5 --- apps/solidcraft/src/control_server.rs | 59 ++++- crates/engine/src/control_pending.rs | 161 +++++++++++++ crates/engine/src/lib.rs | 1 + crates/mcp/src/backend.rs | 274 ++++++++++++++++++++-- crates/mcp/src/server.rs | 5 +- crates/mcp/src/tests.rs | 319 +++++++++++++++++++++++++- crates/mcp/src/tools.rs | 257 ++++++++++++++++++--- docs/control-protocol.md | 15 +- docs/mcp.md | 39 +++- 9 files changed, 1066 insertions(+), 64 deletions(-) create mode 100644 crates/engine/src/control_pending.rs diff --git a/apps/solidcraft/src/control_server.rs b/apps/solidcraft/src/control_server.rs index c64f21079..ea4a65d4d 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, } @@ -324,6 +327,35 @@ fn watch(reply: Receiver, ticket: Ticket) -> Receiver { 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, 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.rs new file mode 100644 index 000000000..72511bd5a --- /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::()), + } +} + +#[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 e9cbf9d8d..b69f50091 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 585a2b090..1e168ca41 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; /// 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, + 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 { + 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, + /// A request still running in the app; its reply waits on `conn`. + outstanding: Option, + /// An outstanding request's end, once a later call waited for it (for `pending`). + settled: Option, + 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::().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 { +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 { + 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 { + 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 { + 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 { + // 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 { + 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 adfe1567a..a40c00f72 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, diff --git a/crates/mcp/src/tests.rs b/crates/mcp/src/tests.rs index dd664b40f..3d82bfc11 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)>>) { + 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::::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 { + 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 6f21fd120..231e2b67e 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 { 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 { 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) -> Result { 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) -> Result 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) -> Result) -> 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 { + 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> { + 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) -> Result { @@ -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) -> 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 = 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::>(), + "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) -> 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) -> 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 = 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::>(), "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, 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 = - 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 = 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 = 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::>(), "results": results, }), true, diff --git a/docs/control-protocol.md b/docs/control-protocol.md index def9c3b1b..fb059e4e6 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": , "method": …, "done": false}` while it runs, then `{"pending": , "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:` (the button alone: `button:`; a drop-down row: `dropdown:`, highlighted `dropdown_hot:`, its pin `dropdown_pin:`; Customize Toolbar's check boxes `customize:`), ribbon tabs `tab:` (MODEL, SURFACE, ASSEMBLE, INSERT, INSPECT, MANAGE, VIEW, SHEET METAL; contextual SKETCH; workspace RENDER), panel labels `panel::` (also `ribbon:section::
`), document overflow list `tab:overflow`, workspace column `ribbon:workspace`, command-search launcher `ribbon:search`, browser rows `row: