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 <noreply@anthropic.com>
This commit is contained in:
SS-EN
2026-10-24 02:41:41 +00:00
committed by GitHub
parent 46fca160e1
commit 6c6ffe4802
9 changed files with 1066 additions and 64 deletions
+56 -3
View File
@@ -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.
+161
View File
@@ -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"));
}
}
+1
View File
@@ -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;
+257 -17
View File
@@ -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}`")),
}
}
+3 -2
View File
@@ -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>,
+317 -2
View File
@@ -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]
+226 -31
View File
@@ -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,
+11 -4
View File
@@ -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. |
+34 -5
View File
@@ -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,