diff --git a/crates/benchup-app/src/agent_link.rs b/crates/benchup-app/src/agent_link.rs index f33355a..0275f75 100644 --- a/crates/benchup-app/src/agent_link.rs +++ b/crates/benchup-app/src/agent_link.rs @@ -25,7 +25,7 @@ //! denying refuses the waiting calls. While the agent is editing, the status //! bar offers "Take control", after which its changes wait for a grant again. use super::*; -use benchup_tools::{Call, ToolEnv, batch, pairing}; +use benchup_tools::{Call, ToolEnv, ToolOutcome, batch, pairing}; use serde_json::{Value, json}; use std::collections::VecDeque; @@ -1312,6 +1312,19 @@ impl BenchUpApp { let outcome = match arguments { Err(error) => Err(json!({"ok": false, "error": error, "hint": "Refer to an earlier call as \"$N.field\" (N counts calls from 1), e.g. \"$1.created[0]\"."})), + // Activity reports are calls of their own. Agents following + // the guide sometimes put one in a batch; skipping it keeps + // the batch, and the $N numbering of the calls after it. + Ok(_) if name == "agent_activity" => Ok(ToolOutcome { + result: json!({"ok": true, "ignored": true, + "note": "agent_activity is reported as a call of its own; inside a batch it is ignored."}), + ok: true, + mutated: false, + created: Vec::new(), + modified: Vec::new(), + erased: Vec::new(), + joints: Vec::new(), + }), Ok(_) if matches!(name.as_str(), "run_batch" | "undo" | "render_view") => { Err(json!({"ok": false, "error": tr!("agent_link.error.nested_session", tool = name)})) } diff --git a/crates/benchup-app/src/agent_link_tests.rs b/crates/benchup-app/src/agent_link_tests.rs index 5a82d55..26981b4 100644 --- a/crates/benchup-app/src/agent_link_tests.rs +++ b/crates/benchup-app/src/agent_link_tests.rs @@ -99,6 +99,20 @@ fn viewport_feedback_tracks_observed_work_and_document_lifetime() { assert!(!setup.app.agent_link.viewport_frame(clock(), None).animated()); } +#[test] +fn activity_reports_inside_a_batch_are_skipped_without_breaking_references() { + let mut setup = Setup::paired(); + let calls = json!([ + {"tool": "agent_activity", "arguments": {"phase": "preparing"}}, + {"tool": "create_board", "arguments": board("After report", 0.)}, + {"tool": "rename", "arguments": {"id": "$2.created[0]", "name": "Renamed"}} + ]); + let answer = setup.call("run_batch", json!({"calls": calls})); + assert_eq!(answer["ok"], true, "{answer}"); + assert_eq!(answer["result"]["results"][0]["ignored"], true, "{answer}"); + assert_eq!(answer["result"]["results"][2]["objects"][0]["name"], "Renamed", "{answer}"); +} + #[test] fn failed_and_previewed_edits_never_start_geometry_transitions() { let mut setup = Setup::paired(); diff --git a/crates/benchup-cli/evals/README.md b/crates/benchup-cli/evals/README.md index 48b8161..f928548 100644 --- a/crates/benchup-cli/evals/README.md +++ b/crates/benchup-cli/evals/README.md @@ -13,6 +13,8 @@ There are two layers: # give each agent the prompt in /tmp/benchup-eval5/prompts/.md, verbatim ``` + To run the cases against the project open in BenchUp (desktop or web) instead of a file, add `--live --token ` (and `--port` if BenchUp uses another one). Open each case's `file` in BenchUp before starting its agent, and run the cases one at a time, since one BenchUp serves one bridge. [Round 7](results/round-7-live.md) was run this way. + ## Files - `cases.json` — the cases: request, seed project, mode (`cli`, or `mcp` through `mcp_call.py`), the tools it is expected to exercise, and the reference solution with what `check_model` must say about it. diff --git a/crates/benchup-cli/evals/prompt.md b/crates/benchup-cli/evals/prompt.md index 207e6c5..ee0a44f 100644 --- a/crates/benchup-cli/evals/prompt.md +++ b/crates/benchup-cli/evals/prompt.md @@ -4,7 +4,7 @@ USER REQUEST: "{request}" SETUP AND RULES -- Your working folder is {dir} . Work only there. Start EVERY shell command with: export PATH={bin}:$PATH && cd {dir} && +- Your working folder is {dir} . Work only there. Start EVERY shell command with: export {exports} && cd {dir} && {access} - Do NOT read any source code, README, docs or file of the BenchUp repository, ~/.cargo, or other evaluation folders ({root}), or anywhere else about benchup. No web searches. A real user would not have them. - Do NOT run `benchup open` (several evaluations run at once and would fight over the desktop app). Everything else is allowed. diff --git a/crates/benchup-cli/evals/results/round-7-live.md b/crates/benchup-cli/evals/results/round-7-live.md new file mode 100644 index 0000000..77d0617 --- /dev/null +++ b/crates/benchup-cli/evals/results/round-7-live.md @@ -0,0 +1,76 @@ +# Round 7, live (16 November 2026) + +This round is item 3 of [#55](https://github.com/BenchUp3D/benchup/issues/55): the twelve original cases (01–12) rerun against the project open in BenchUp instead of a file, through `benchup … --live` and `benchup bridge`. Each agent got the usual prompt, prepared with `setup.py --live`, so it learned the tools only from `benchup --help`, the guide and the tool output, and was told the project was open in the app. The requests were not changed. + +The cases ran one at a time on each surface, because one BenchUp serves one bridge: + +- **Desktop:** a `dev-desktop` build of `main` on macOS, started for each case with its own `BENCHUP_DATA_DIR`, the agent connection turned on and the case's file passed on the command line. +- **Web, Chrome 157:** the same commit served by `trunk serve` on `http://127.0.0.1:8090`, with its own bridge port (47616) and token. Each case's file was opened through File → Open. +- **Web, Safari:** not run yet (see below). + +Each cell is the number of `benchup` commands, with those that returned an error in brackets. Live counts include two to four `agent_activity` calls per case, which file mode does not have. Every result was checked independently afterwards with `check_model` and an iso render taken live from the app. + +| # | Case | R5 (file) | R7 desktop | R7 Chrome | Result in R7 (both surfaces) | +|---|---|---|---|---|---| +| 01 | Lengthen the desk | 23 (1) | 29 (0) | 32 (0) | ✅ lengthened at the front, top kept full width past the post | +| 02 | Five shelves to four | 17 (0) | 21 (0) | 20 (0) | ✅ gaps of 345.6 mm, joints flipped in a separate batch | +| 03 | Dining table | 18 (0) | 20 (1) | 21 (0) | ✅ 8/8 joints | +| 04 | Chest of drawers | 20 (0) | 27 (1) | 24 (0) | ✅ 24/24 joints, one component | +| 05 | Back in a rabbet and plinth | 43 (2) | 21 (0) | 20 (0) | ✅ routed rabbet, back whole, plinth in two halves | +| 06 | Solid oak 19 mm | 25 (3) | 24 (0) | 20 (0) | ✅ `change_thickness` without workarounds | +| 07 | Bedside table with curved sides | 16 (0) | 22 (1) | 22 (1) | ✅ 6/6 joints, 2 profiles | +| 08 | Leaning ladder shelf | 27 (1) | 34 (0) | 26 (0) | ✅ 8/8 stopped housings | +| 09 | Workshop dimensions | 18 (0) | 13 (0) | 16 (0) | ✅ the ten reversed joints of the seed are reported, not touched | +| 10 | Modules, components and tags | 25 (2) | 27 (1) | 27 (0) | ⚠️ partial on purpose, alternative saved, as in every round | +| 11 | Cut list and sheets | 12 (0) | 13 (0) | 15 (0) | ✅ 2 sheets, dry run only, project unchanged | +| 12 | A shelf that does not fit | 14 (0) | 15 (0) | 12 (0) | ✅ refused, 491 mm alternative saved | +| | **Total** | **258 (9)** | **266 (4)** | **255 (1)** | 11 ✅, 1 ⚠️ on each surface | + +Live mode behaved like file mode. No agent hit a bridge or connection error, and no call timed out. The extra commands are the `agent_activity` reports and, on the desktop, one agent (08) that placed its dimensions three times. The error in 10 on the desktop was a deliberate trial. + +## What was checked about live mode + +- **Undo:** a batch is one step in BenchUp, for example `Agent: push_pull, split_face, merge_faces, …`, and `benchup undo --live` / `redo --live` step through it. +- **Dry runs:** `call --live --dry-run` leaves the open model and its undo history untouched (checked by counting objects before and after, and by undoing the previous step). Agents in 02, 04 and 11 relied on this. +- **Reconnection:** in Chrome, `trunk` reloaded the page right after case 02. BenchUp restored the project from local storage and connected to the bridge again by itself; the change was kept. +- **Opening another project:** on the web, File → Open while the agent's changes were unsaved showed the unsaved-changes modal (Discard changes, Save, Cancel), as for any other change. +- **Status:** the web status bar showed "Agente conectado" (the app was in Spanish) while the bridge served it. + +Not covered here: the grant/deny prompt and Take control (they need someone drawing in the app at the time), shared projects and leases (they need the server). + +## Transport from the published web app + +- **Origin:** `https://benchup3d.github.io/benchup/` now redirects to `https://benchup.io`, so the published app loads from that origin. The bridge only allowed `https://benchup3d.github.io` and answered the published app with HTTP 403. Fixed in this branch: the bridge allows both origins (`bridge.rs`, with a test). +- **Chrome 157:** a WebSocket from `https://benchup.io` to `ws://127.0.0.1` waits for the local network access permission (`local-network-access` is `prompt`). Nobody answered the prompt in this run; after about 240 s the socket failed with code 1006. Still to do: allow the prompt and confirm the connection opens, then check that BenchUp says what is happening while the prompt waits. +- **Safari:** still to do. The question from #73 is whether Safari lets an `https` page open `ws://127.0.0.1`. The local build on `http://127.0.0.1` does not answer it. + +## Findings + +### Tool bugs and unclear output (benchup-tools / CLI) + +1. **`agent_activity` is missing from `benchup tools`**, and `benchup tools agent_activity` fails with "unknown tool agent_activity", although the guide tells agents to call it in live mode (03, 04, 07 and others). +2. **`agent_activity` inside a `--batch` fails** with "unknown tool agent_activity" and aborts the batch; the guide's "use `{"phase":"preparing"}` while preparing changes" made an agent put it there, and it then had to renumber every `$N` (07, desktop). +3. **`add_joint` accepts a `tongue_groove` whose `a` runs right through `b`**, and `check_model` then names only one of the two boards the shelf passes through (12, desktop). +4. **`flip_joint` accepts `{"id": …}`** although its schema only has `ids` and `additionalProperties: false`, without a warning (10, Chrome). +5. **`check_model only_new`** still reports existing issues as new when the boards are recreated (10, desktop; the `group` case from round 5 is fixed). +6. **`push_pull` on a face that borders a notch** stretches the neighbouring faces and returns `created: []`; it also returns both `face_id` and `new_face_id` with the same value (01). +7. **`change_thickness`** reports an intermediate `length_mm` (481.5) in `joint_adjustments` and the final one (481) in `butt_adjustments` (06, Chrome). +8. **`add_dimension` with `axis`** anchors the line at the midpoint of its points when they differ off the axis, so offsets need to be compensated by hand; ends attach only when given to about five decimals on rotated geometry (08). +9. **`render`** clips long text notes at the image edge without saying so (03, 04, 08), and lists edge-on dimensions of other planes as overlaps (09). +10. **`add_profile` and `get_object`** do not say which face received `width_mm` and which `depth_mm` (05, both surfaces, as in round 6). + +### Guide gaps (docs/agent-guide.md) + +- Say that `agent_activity` is a live-only call that is not listed by `benchup tools` and must not go in a batch, and give its phases. +- Say that dry-run ids match the real run in live mode; the guide says they differ (04). +- The "Lengthening a piece" recipe should cover an end face next to a notch: push, split the new side face at the notch line, push the piece out (01, both surfaces). +- The `rabbet` row of the joint table still reads as a rabbet but cuts a tongue in a slot; lead with the routed profile (05). +- The drawer recipe should say how drawers are supported (runners, rails) and give the gap arithmetic for N equal drawers (04). +- The plinth recipe assumes a bottom panel; the bookcase has none (05). +- Organising an existing model: parts shared between modules, and the order of tag, rename and group calls since grouping changes ids (10). +- `benchup guide` is about 29 KB, and every agent had to read it from a saved file; a table of contents or `benchup guide
` would help. + +### Live-mode setup + +- The pairing token is the only thing an agent needs besides the command, and every agent found the `--live` mode from `benchup --help` alone. +- The project name in results is the file stem (`table`), not a title (`Table`); agents noticed but were not confused. diff --git a/crates/benchup-cli/evals/results/round-8-live.md b/crates/benchup-cli/evals/results/round-8-live.md new file mode 100644 index 0000000..bafb82c --- /dev/null +++ b/crates/benchup-cli/evals/results/round-8-live.md @@ -0,0 +1,33 @@ +# Round 8, live (17 November 2026) + +A short round to confirm the fixes made after [round 7](round-7-live.md), on the seven cases those findings came from. As in round 7, each agent edited the project open in a desktop build of BenchUp through `benchup … --live`, with the prompts from `setup.py --live`. Each cell is the number of `benchup` commands, with errors in brackets; results were checked independently with `check_model` and an iso render taken from the app. + +| # | Case | R7 desktop | R8 desktop | Result in R8 | +|---|---|---|---|---| +| 01 | Lengthen the desk | 29 (0) | 28 (0) | ✅ followed the new notch recipe (push, split the side face, push, merge) without dry-run exploration | +| 04 | Chest of drawers | 27 (1) | 24 (0) | ✅ wooden runners from the recipe, butted against the sides; no `agent_activity` error | +| 05 | Back in a rabbet and plinth | 21 (0) | 26 (0) | ✅ went straight to the routed rabbet; 5 of its commands checked the profile's orientation | +| 07 | Bedside table with curved sides | 22 (1) | 21 (0) | ✅ no batch broken by `agent_activity` | +| 08 | Leaning ladder shelf | 34 (0) | **24 (0)** | ✅ dimensions placed once, instead of three times | +| 10 | Modules, components and tags | 27 (1) | 26 (1) | ⚠️ partial on purpose, as in every round; tagged before grouping and left the divider outside both modules, as the guide now says. The error was a deliberate trial | +| 12 | A shelf that does not fit | 15 (0) | 18 (1) | ✅ `check_model` now names both boards the shelf runs through, the divider included. The error was a deliberate call to see `measure_space`'s fields | +| | **Total** | **175 (3)** | **167 (2)** | 6 ✅, 1 ⚠️ | + +No agent hit `unknown tool agent_activity`, and none of the remaining errors came from the tools. + +## Fixed after round 7 + +- `benchup tools` lists `agent_activity`, marked `live_only`, and `benchup tools agent_activity` shows its schema. Inside a batch, BenchUp skips it with a note instead of failing the batch; in file mode it fails with a message that says it is live-only. +- `check_model` reports a board that runs right through another even when a housing joint (`tongue_groove`, `rabbet`, `groove`) joins them. Through tenons and cross halvings are not affected. +- `render` marks a text note that runs off the image with `cut_off`, and lists them in `texts_cut_off` with a hint. +- `add_dimension` documents that, with `axis`, the line goes through the midpoint of its points. +- The guide covers: `agent_activity` as a call of its own, dry-run ids, the notch case of lengthening, the routed rabbet first in the joint table, drawer runners and the front height of N equal drawers, a plinth without a bottom panel, and organising a model into modules. + +## Still open + +- `add_profile` and `get_object` do not say which face got `width_mm` and which `depth_mm` (05, since round 6). Answering it needs the router geometry from the core. +- `flip_joint` and other tools that take `ids` also accept `"id"`, on purpose, but the schema does not show it; only some tools accept it, so the schema cannot say so in one place. +- `check_model only_new` reports existing issues as new when boards are recreated (10). +- A way to stop a housing short of the front edge, for tops and bottoms housed flush with the top of the sides (04). +- `benchup guide` is now about 31 KB; agents read it from a saved file. A table of contents or `benchup guide
` would help. +- The cut list gives a rotated or shaped board's blank as its bounding box (08). diff --git a/crates/benchup-cli/evals/setup.py b/crates/benchup-cli/evals/setup.py index 9f71d7d..1133ba1 100755 --- a/crates/benchup-cli/evals/setup.py +++ b/crates/benchup-cli/evals/setup.py @@ -2,13 +2,19 @@ """Prepare a round of the agent evaluation (see README.md). python3 crates/benchup-cli/evals/setup.py --round 5 [--cases 01,13] [--binary target/release/benchup] + python3 crates/benchup-cli/evals/setup.py --round 7 --live --token TOKEN [--port 47615] [--cases 01,13] Creates /tmp/benchup-eval/ with the binary in bin/, one folder per case with its seed project, and prompts/.md with the exact prompt to -give each agent. Prints a JSON list of {id, dir, prompt}. Run it from the +give each agent. Prints a JSON list of {id, dir, prompt, file}. Run it from the repository root; it never builds anything. + +With --live, the agents edit the project open in BenchUp through +`benchup ... --live` instead of the file: open each case's `file` in BenchUp +(new cases get an empty project to open) and run the cases one at a time, +since one BenchUp serves one bridge. The requests stay the same. """ -import argparse, json, os, shutil, sys +import argparse, json, os, shlex, shutil, subprocess, sys from pathlib import Path HERE = Path(__file__).resolve().parent @@ -19,6 +25,11 @@ "`python3 {bin}/mcp_call.py FILE list` (tools and schemas), `... FILE call TOOL 'JSON'` and " "`... FILE render VIEW OUT.png`. Start with the server's get_guide tool. Do NOT run the `benchup` " "command directly.") +LIVE_ACCESS = ("- The project is open in the BenchUp app on this computer: {opened}. Edit it there, live, with " + "`benchup` commands that take `--live` instead of a file; the pairing token and port are already set by " + "the command prefix. Do not create, read or write .bup files on disk, and do not start or stop a bridge " + "yourself. Learn the CLI ONLY from `benchup --help`, what the help points you to (e.g. `benchup guide`, " + "`benchup tools`, `benchup tools `) and the outputs/errors it gives you.") def main(): @@ -27,7 +38,15 @@ def main(): parser.add_argument("--cases", help="comma-separated case number prefixes, e.g. 01,13 (default: all)") parser.add_argument("--binary", default=str(ROOT / "target/release/benchup")) parser.add_argument("--out", help="default /tmp/benchup-eval") + parser.add_argument("--live", action="store_true", help="agents edit the project open in BenchUp (--live)") + parser.add_argument("--token", help="with --live: the pairing token shown in BenchUp") + parser.add_argument("--port", type=int, help="with --live: the bridge port set in BenchUp (default 47615)") args = parser.parse_args() + if args.live and not args.token: + sys.exit("--live needs --token, the pairing token from BenchUp (Settings → Agent connection)") + if args.live and any(c["mode"] == "mcp" for c in json.loads((HERE / "cases.json").read_text())["cases"] + if not args.cases or any(c["id"].startswith(w) for w in args.cases.split(","))): + sys.exit("--live runs CLI cases only; leave MCP cases out with --cases") binary = Path(args.binary) if not binary.is_file(): sys.exit(f"no benchup binary at {binary}; build it with `cargo build --release -p benchup-cli` first") @@ -49,17 +68,31 @@ def main(): seed = manifest["seeds"][case["seed"]] if seed: shutil.copy2(ROOT / seed, folder / case["file"]) + elif args.live: + # BenchUp needs a project to open; the request still asks to create it. + subprocess.run([str(out / "bin/benchup"), "new", str(folder / case["file"]), + "--name", Path(case["file"]).stem.capitalize()], check=True, capture_output=True) mcp = case["mode"] == "mcp" + exports = f"PATH={out / 'bin'}:$PATH" + if args.live: + exports += f" BENCHUP_AGENT_TOKEN={shlex.quote(args.token)}" + if args.port: + exports += f" BENCHUP_BRIDGE_PORT={args.port}" + opened = (f"`{case['file']}`" if seed else + f"an empty project named `{Path(case['file']).stem.capitalize()}`, standing for `{case['file']}`") + access = LIVE_ACCESS.format(opened=opened) + else: + access = (MCP_ACCESS if mcp else CLI_ACCESS).format(bin=out / "bin") prompt = template.format( request=case["request"], dir=folder, bin=out / "bin", root=out.parent / "benchup-eval*", - access=(MCP_ACCESS if mcp else CLI_ACCESS).format(bin=out / "bin"), - unit="MCP tool calls" if mcp else "benchup commands", + access=access, exports=exports, unit="MCP tool calls" if mcp else "benchup commands", ) - if not seed: + if not seed and not args.live: prompt = prompt.replace("Work only there.", "Work only there. The project does not exist yet; create it there.") path = out / "prompts" / f"{case['id']}.md" path.write_text(prompt) - listing.append({"id": case["id"], "title": case["title"], "dir": str(folder), "prompt": str(path)}) + listing.append({"id": case["id"], "title": case["title"], "dir": str(folder), "prompt": str(path), + "file": str(folder / case["file"])}) print(json.dumps(listing, indent=1, ensure_ascii=False)) diff --git a/crates/benchup-cli/src/bridge.rs b/crates/benchup-cli/src/bridge.rs index 4e74a3f..7eefa3c 100644 --- a/crates/benchup-cli/src/bridge.rs +++ b/crates/benchup-cli/src/bridge.rs @@ -54,6 +54,9 @@ use tungstenite::{ pub const DEFAULT_PORT: u16 = pairing::DEFAULT_PORT; /// The published web app. Local development servers are always allowed too. pub const DEFAULT_ORIGIN: &str = "https://benchup3d.github.io"; +/// Origins that serve the published web app: the GitHub Pages address +/// redirects to the custom domain, so pages actually load from the latter. +pub const PUBLISHED_ORIGINS: [&str; 2] = [DEFAULT_ORIGIN, "https://benchup.io"]; pub const TOKEN_ENV: &str = "BENCHUP_AGENT_TOKEN"; pub const PORT_ENV: &str = "BENCHUP_BRIDGE_PORT"; pub const MIN_TOKEN_LEN: usize = 16; @@ -152,7 +155,7 @@ fn now_ms() -> u64 { /// `--allow-origin`. pub fn origin_allowed(origin: Option<&str>, extra: &[String]) -> bool { let Some(origin) = origin else { return true }; - if origin == DEFAULT_ORIGIN || extra.iter().any(|o| o == origin) { + if PUBLISHED_ORIGINS.contains(&origin) || extra.iter().any(|o| o == origin) { return true; } ["http://localhost", "http://127.0.0.1"].iter().any(|base| { diff --git a/crates/benchup-cli/src/bridge_tests.rs b/crates/benchup-cli/src/bridge_tests.rs index a97210f..6f46a21 100644 --- a/crates/benchup-cli/src/bridge_tests.rs +++ b/crates/benchup-cli/src/bridge_tests.rs @@ -81,6 +81,10 @@ fn echo_app(hub: &Hub) -> std::thread::JoinHandle<()> { fn origins_are_limited_to_the_web_app_and_local_servers() { assert!(origin_allowed(None, &[])); assert!(origin_allowed(Some(DEFAULT_ORIGIN), &[])); + // The GitHub Pages address redirects there, so the app loads from it. + assert!(origin_allowed(Some("https://benchup.io"), &[])); + assert!(!origin_allowed(Some("https://benchup.io.evil.example"), &[])); + assert!(!origin_allowed(Some("http://benchup.io"), &[])); assert!(origin_allowed(Some("http://localhost:8080"), &[])); assert!(origin_allowed(Some("http://127.0.0.1"), &[])); assert!(!origin_allowed(Some("https://evil.example"), &[])); diff --git a/crates/benchup-cli/src/main.rs b/crates/benchup-cli/src/main.rs index 515a6e7..846cc7d 100644 --- a/crates/benchup-cli/src/main.rs +++ b/crates/benchup-cli/src/main.rs @@ -178,16 +178,32 @@ fn pretty(value: &Value) -> String { } fn tools(args: Args) -> Result { + // `agent_activity` is answered by BenchUp itself, not by the tool layer, + // so it only exists with --live; list it anyway, marked as such, since + // the guide asks agents to call it. + let activity = mcp::agent_activity_tool(); + let activity_name = activity["name"].as_str().unwrap_or_default().to_owned(); match args.positional.as_slice() { - [] if args.flag("--json") => Ok(ok(Value::Array(mcp_tools()))), - [] if args.flag("--names") => Ok(ok(json!(definitions().into_iter().map(|d| d.name).collect::>()))), + [] if args.flag("--json") => { + let mut list = mcp_tools(); + list.push(activity); + Ok(ok(Value::Array(list))) + } + [] if args.flag("--names") => { + let mut names: Vec = definitions().into_iter().map(|d| d.name).collect(); + names.push(activity_name); + Ok(ok(json!(names))) + } [] => { - let list: Vec = definitions() + let mut list: Vec = definitions() .into_iter() .map(|d| json!({"name": d.name, "changes_model": is_mutating(&d.name), "description": d.description})) .collect(); + list.push(json!({"name": activity_name, "changes_model": false, "live_only": true, "description": activity["description"]})); Ok(ok(Value::Array(list))) } + [name] if *name == activity_name => Ok(ok(json!({"name": activity_name, "live_only": true, + "description": activity["description"], "inputSchema": activity["inputSchema"]}))), [name] => definitions() .into_iter() .find(|d| &d.name == name) diff --git a/crates/benchup-cli/src/mcp.rs b/crates/benchup-cli/src/mcp.rs index ef0d91e..e708948 100644 --- a/crates/benchup-cli/src/mcp.rs +++ b/crates/benchup-cli/src/mcp.rs @@ -43,10 +43,10 @@ fn render_view_tool() -> Value { }) } -fn agent_activity_tool() -> Value { +pub(crate) fn agent_activity_tool() -> Value { json!({ "name": "agent_activity", - "description": "Report the lifetime of your work in the open BenchUp app. Call with phase: analyzing BEFORE you start reading/planning, preparing while preparing changes, and finished AFTER your final verification and BEFORE replying to the user, including when stopping after an error. The robot stays visible between tool calls until finished. Ordinary calls update its looking/gear animation automatically. This changes no model data, selection or undo history. Only available in live mode.", + "description": "Report the lifetime of your work in the open BenchUp app. Call with phase: analyzing BEFORE you start reading/planning, preparing while preparing changes, and finished AFTER your final verification and BEFORE replying to the user, including when stopping after an error. The robot stays visible between tool calls until finished. Ordinary calls update its looking/gear animation automatically. This changes no model data, selection or undo history. Only available in live mode, and as a call of its own: inside a batch it is ignored.", "inputSchema": {"type": "object", "properties": { "phase": {"type": "string", "enum": ["analyzing", "preparing", "finished"]} }, "required": ["phase"], "additionalProperties": false}, diff --git a/crates/benchup-cli/tests/cli.rs b/crates/benchup-cli/tests/cli.rs index ad26665..0d1cd52 100644 --- a/crates/benchup-cli/tests/cli.rs +++ b/crates/benchup-cli/tests/cli.rs @@ -172,6 +172,14 @@ fn tools_lists_schemas() { let one = json_out(&benchup(&["tools", "create_board"], None)); assert_eq!(one["inputSchema"]["required"], json!(["name", "origin_mm", "size_mm"])); assert_eq!(benchup(&["tools", "nope"], None).status.code(), Some(2)); + // The guide asks live agents to call agent_activity, so it is listed and + // documented too, marked live-only. + let activity = list.as_array().unwrap().iter().find(|t| t["name"] == "agent_activity").unwrap(); + assert_eq!(activity["live_only"], json!(true)); + let one = json_out(&benchup(&["tools", "agent_activity"], None)); + assert_eq!(one["inputSchema"]["properties"]["phase"]["enum"], json!(["analyzing", "preparing", "finished"])); + let names = json_out(&benchup(&["tools", "--names"], None)); + assert!(names.as_array().unwrap().contains(&json!("agent_activity"))); } #[test] diff --git a/crates/benchup-tools/src/ops.rs b/crates/benchup-tools/src/ops.rs index a05911d..e9adac3 100644 --- a/crates/benchup-tools/src/ops.rs +++ b/crates/benchup-tools/src/ops.rs @@ -314,7 +314,7 @@ pub fn definitions() -> Vec { json!({"ids": ids()}), &["ids"]), def("flip_joint", "Swap a joint's a and b (the board that carries the tenon or tongue and the one that receives it), keeping its kind and settings and re-picking the orientation. Use it when check_model reports joint_roles_reversed.", json!({"ids": ids()}), &["ids"]), - def("add_dimension", "Add a dimension between two points. It measures the straight distance between them, or only along axis (x, y or z) when given. A point exactly on a vertex, edge or face attaches to it and follows it when the part moves; there is no snapping to nearby points. offset_mm moves the dimension line away from the measured points, perpendicular to them (e.g. [0, -150, 0] draws it 150 mm in front). Returns length_mm and whether each end attached.", + def("add_dimension", "Add a dimension between two points. It measures the straight distance between them, or only along axis (x, y or z) when given. A point exactly on a vertex, edge or face attaches to it and follows it when the part moves; there is no snapping to nearby points. offset_mm moves the dimension line away from the measured points, perpendicular to them (e.g. [0, -150, 0] draws it 150 mm in front). With axis, the line is drawn through the midpoint of the two points, so when they differ off the axis, measure offset_mm from that midpoint. Returns length_mm and whether each end attached.", json!({"start_mm": vec3(), "end_mm": vec3(), "offset_mm": vec3(), "axis": axis_enum()}), &["start_mm", "end_mm", "offset_mm"]), def("add_text", "Add a text note anchored at point_mm; offset_mm places the label away from the anchor with a leader line ([0, 0, 0] puts it on the point).", json!({"point_mm": vec3(), "offset_mm": vec3(), "text": text()}), &["point_mm", "offset_mm", "text"]), @@ -1681,6 +1681,13 @@ fn out_of_range(model: &Model, done: &Done) -> bool { /// exactly as it was; a successful one records the turn's `before` snapshot. pub fn execute(model: &mut Model, call: &Call, env: &mut ToolEnv) -> ToolOutcome { let name = call.name.as_str(); + if name == "agent_activity" { + // Answered by BenchUp itself (live mode only), never by the tool layer. + return error_outcome( + "agent_activity is only available in live mode".into(), + Some("It reports your progress to the open BenchUp app: call it on its own with `benchup call --live agent_activity '{\"phase\":\"analyzing\"}'`. Editing a file needs no activity reports.".into()), + ); + } if !is_known(name) { let names: Vec<_> = TOOLS.iter().map(|(n, _)| *n).collect(); return error_outcome(format!("unknown tool {name}"), Some(format!("Available tools: {}", names.join(", ")))); diff --git a/crates/benchup-tools/src/ops_tests.rs b/crates/benchup-tools/src/ops_tests.rs index 4dfa66c..e3dd0c9 100644 --- a/crates/benchup-tools/src/ops_tests.rs +++ b/crates/benchup-tools/src/ops_tests.rs @@ -75,6 +75,7 @@ fn argument_and_id_errors_are_structured_and_harmless() { let (mut model, mut env) = (Model::default(), ToolEnv::default()); let leg = board(&mut model, &mut env, "Leg", [0., 0., 0.], [40., 40., 700.]); assert!(err(&mut model, &mut env, "nope", json!({})).contains("unknown tool")); + assert!(err(&mut model, &mut env, "agent_activity", json!({"phase": "analyzing"})).contains("only available in live mode")); assert!(err(&mut model, &mut env, "move", json!({"ids": [leg]})).contains("invalid arguments")); assert!(err(&mut model, &mut env, "move", json!({"ids": [leg], "delta_mm": [1, 2, 3], "extra": 1})).contains("invalid arguments")); assert!(err(&mut model, &mut env, "move", json!({"ids": "a", "delta_mm": [1, 2, 3]})).contains("invalid arguments")); @@ -997,6 +998,27 @@ fn check_model_reports_boards_passing_through_and_thickness() { assert_eq!(check["errors"], 1); } +#[test] +fn check_model_reports_a_housed_board_that_crosses_the_other() { + // A housing joint does not make a board that runs right through another + // buildable: the groove would cut the divider, and the shelf goes on. + let (mut model, mut env) = (Model::default(), ToolEnv::default()); + let divider = board(&mut model, &mut env, "Divider", [491., 0., 0.], [18., 300., 1800.]); + let shelf = board(&mut model, &mut env, "Long shelf", [9., 0., 1000.], [1200., 300., 18.]); + ok(&mut model, &mut env, "add_joint", json!({"a": shelf, "b": divider, "kind": "tongue_groove"})); + let check = ok(&mut model, &mut env, "check_model", json!({})).result; + let through: Vec<&Value> = check["issues"].as_array().unwrap().iter().filter(|i| i["kind"] == "passes_through").collect(); + assert_eq!(through.len(), 1, "{check}"); + assert!(through[0]["message"].as_str().unwrap().starts_with("Divider passes right through Long shelf"), "{check}"); + // A shelf that only enters the divider is fine. + let (mut model, mut env) = (Model::default(), ToolEnv::default()); + let divider = board(&mut model, &mut env, "Divider", [491., 0., 0.], [18., 300., 1800.]); + let shelf = board(&mut model, &mut env, "Shelf", [9., 0., 1000.], [491., 300., 18.]); + ok(&mut model, &mut env, "add_joint", json!({"a": shelf, "b": divider, "kind": "tongue_groove"})); + let check = ok(&mut model, &mut env, "check_model", json!({})).result; + assert_eq!(check["errors"], 0, "{check}"); +} + #[test] fn dimensions_measure_along_an_axis_and_report_attachment() { let (mut model, mut env) = (Model::default(), ToolEnv::default()); diff --git a/crates/benchup-tools/src/render.rs b/crates/benchup-tools/src/render.rs index 3f9968d..8a98f21 100644 --- a/crates/benchup-tools/src/render.rs +++ b/crates/benchup-tools/src/render.rs @@ -443,6 +443,7 @@ pub fn render(model: &Model, view: &str, width: u32, height: u32) -> Result Result w as f64 || first - half_h < 0. || last + half_h > h as f64 { + note["cut_off"] = json!(true); + cut_off.push(*id); + } + notes.push(note); } let overlaps_rect = |r: &[f64; 4], s: &[f64; 4]| r[0] < s[2] && s[0] < r[2] && r[1] < s[3] && s[1] < r[3]; let line_hits_rect = |l: &[f64; 4], r: &[f64; 4]| { @@ -482,6 +494,10 @@ pub fn render(model: &Model, view: &str, width: u32, height: u32) -> Result = rendered.info["texts"].as_array().unwrap().iter().filter(|n| n["cut_off"] == true).collect(); + assert_eq!(cut.len(), 1, "{}", rendered.info); + assert!(cut[0]["text"].as_str().unwrap().starts_with("A NOTE")); + assert_eq!(rendered.info["texts_cut_off"].as_array().unwrap().len(), 1); + } + #[test] fn the_model_is_drawn_and_overlapping_dimensions_are_reported() { let model = shelf_with_dimensions(); @@ -556,6 +587,7 @@ mod tests { // Seen from the side, the vertical dimensions read; from the top they are end-on. let top = render(&model, "top", 200, 200).unwrap(); assert_eq!(top.info["dimensions_end_on"].as_array().unwrap().len(), 2); + assert!(rendered.info.get("texts_cut_off").is_none()); assert_eq!(base64(b"Man"), "TWFu"); assert_eq!(base64(b"Ma"), "TWE="); } diff --git a/crates/benchup-tools/src/review.rs b/crates/benchup-tools/src/review.rs index 5354d3a..5cfb604 100644 --- a/crates/benchup-tools/src/review.rs +++ b/crates/benchup-tools/src/review.rs @@ -1,7 +1,7 @@ //! Read-only reviews an agent cannot do by looking at the model: a cut list and //! a check for problems such as overlapping boards without a joint. use crate::scene::{self, mm, point_mm}; -use benchup_core::{DVec3, Model, StockMaterial, connections::ConnectionOperation, joinery::JointSettings}; +use benchup_core::{DVec3, Model, StockMaterial, connections::ConnectionOperation, joinery::{JointKind, JointSettings}}; use serde_json::{Value, json}; use std::collections::{BTreeMap, BTreeSet}; @@ -288,6 +288,16 @@ fn collect(model: &Model) -> Found { .values() .map(|c| [c.members[0].min(c.members[1]), c.members[0].max(c.members[1])]) .collect(); + // Pairs joined by a housing (tongue and groove, rabbet, groove): one + // board may enter the other, but never cross it completely. Through + // tenons and cross halvings do cross, so they are not listed. + let housed: BTreeSet<[u64; 2]> = model + .connections + .values() + .filter(|c| matches!(&c.operation, ConnectionOperation::Joinery(s) + if matches!(s.kind, JointKind::TongueGroove | JointKind::Rabbet | JointKind::Groove))) + .map(|c| [c.members[0].min(c.members[1]), c.members[0].max(c.members[1])]) + .collect(); let all = boards(model); let checked = &all[..all.len().min(MAX_CHECKED_BOARDS)]; let bounds: Vec<(u64, (DVec3, DVec3), bool)> = checked @@ -301,7 +311,8 @@ fn collect(model: &Model) -> Found { for (i, (a, box_a, aligned_a)) in bounds.iter().enumerate() { for (b, box_b, aligned_b) in &bounds[i + 1..] { let Some(size) = overlap(*box_a, *box_b) else { continue }; - if joined.contains(&[(*a).min(*b), (*a).max(*b)]) { + let pair = [(*a).min(*b), (*a).max(*b)]; + if joined.contains(&pair) && !housed.contains(&pair) { continue; } // Bounding boxes overlap; a notch around the other board means the solids do not. @@ -340,6 +351,10 @@ fn collect(model: &Model) -> Found { ); continue; } + // A housing whose boards do not cross is checked by the joint itself. + if joined.contains(&pair) { + continue; + } let approximate = if *aligned_a && *aligned_b { "" } else { " (measured on bounding boxes; a board is rotated)" }; issue( "warning", diff --git a/docs/agent-guide.md b/docs/agent-guide.md index d6bc08d..588736e 100644 --- a/docs/agent-guide.md +++ b/docs/agent-guide.md @@ -20,14 +20,14 @@ This guide is written for AI agents that edit BenchUp projects through the [`ben - `check_model` finds boards that pass through others, overlaps without a joint, joints that cannot be cut or look reversed, boards thicker or thinner than their material, and loose geometry. It also counts the joints that cut. Read `passed` (no errors or warnings); `ok` only says the check ran. - `get_object` on a joint shows its settings and status. - `get_cut_list` lists the boards to cut; `get_estimate` gives the time to build them. - - `benchup render file.bup --view front` (over MCP, `render_view`) draws the model as a PNG, joints and profiles cut, with dimensions and text notes (in capitals, without accents). Its output lists dimensions whose labels overlap and the notes with their position. It shows the whole model; details of a few millimetres need `--size 2400x1800`. + - `benchup render file.bup --view front` (over MCP, `render_view`) draws the model as a PNG, joints and profiles cut, with dimensions and text notes (in capitals, without accents). Its output lists dimensions whose labels overlap and the notes with their position; a note that runs off the image is marked `cut_off`, so keep notes short or break them into lines. It shows the whole model; details of a few millimetres need `--size 2400x1800`. 5. In the open app (`--live` or `benchup bridge`), the designer sees each change as you make it. With a file, `benchup open file.bup` shows the result in the desktop app. The CLI edits the file, not the open window, but BenchUp versions after 0.7.1 reload the file by themselves about a second after each change (with older versions, run `open` again). If the project has unsaved changes in the app, BenchUp asks the user first: tell them to choose "Reload from disk" to see your edit, because keeping their changes and saving overwrites it. ### Batches, results and dry runs - Every call that changes the model returns `created`, `modified` and `erased` ids. Some return more: `joint_id` (`add_joint`, `set_joint`), `material_id` (`create_stock_material`), `face_id` (`draw_polyline` and `push_pull`), `faces` (`split_face`), `edges` (`add_profile`) and `members` (`group`). `benchup tools ` describes each tool. - Ids are not consecutive, so always take them from results. In a batch, `"$N.field"` is a value from call N's result, counting from 1. Any field works, including nested ones: `"$1.created[0]"`, `"$3.joint_id"`, `"$2.material_id"`, `"$4.members[0].id"`, `"$5.created[-1]"`. A reference may stand in for any argument, even where the schema says integer or uuid. A reference to a list of ids inside a list is spliced in, so `"ids": ["$1.created", "$2.created"]` joins both; other lists, such as a point in `points_mm`, stay one item. Text that is not exactly a reference, such as `"$12.50 hardware"`, is kept as written. -- With the CLI, `--dry-run` reports every result without changing the file; ids made in a dry run differ from the real run. **End a dry-run batch with `check_model` to validate the change before applying it.** `check_model` with `"only_new": true` reports only the problems the batch introduced, leaving out those that were already in the project. Read tools inside a batch see the batch's earlier changes. `--brief` leaves out the object summaries of changing calls and keeps ids and bounds. +- With the CLI, `--dry-run` reports every result without changing the file; ids made in a dry run may differ from the real run, so take ids from the real run's results. **End a dry-run batch with `check_model` to validate the change before applying it.** `check_model` with `"only_new": true` reports only the problems the batch introduced, leaving out those that were already in the project. Read tools inside a batch see the batch's earlier changes. `--brief` leaves out the object summaries of changing calls and keeps ids and bounds. - When a call in a batch fails, nothing is changed. The output names the failed call and shows `earlier_results`, what the calls before it returned. ### Over MCP @@ -44,7 +44,7 @@ Each other call is saved on its own, so prefer `run_batch` for any change of mor `benchup bridge` (MCP) and the CLI's `--live` commands (`benchup call --live …`, `benchup scene --live`) work on the project open in BenchUp, while the designer watches. The tools and batches are the same, with these differences: -- Begin each task with `agent_activity {"phase":"analyzing"}` before reading or planning, and use `{"phase":"preparing"}` while preparing changes. Ordinary calls update the robot's looking/gear mode automatically. The robot stays visible across pauses between calls. After final verification, **always** call `agent_activity {"phase":"finished"}` before replying to the user, including when stopping after an error. From the CLI, use `benchup call --live agent_activity '{"phase":"analyzing"}'` (and likewise for the other phases). Activity reports change no model data, selection, or undo history; they are live-only. +- Begin each task with `agent_activity {"phase":"analyzing"}` before reading or planning, and use `{"phase":"preparing"}` while preparing changes. Ordinary calls update the robot's looking/gear mode automatically. The robot stays visible across pauses between calls. After final verification, **always** call `agent_activity {"phase":"finished"}` before replying to the user, including when stopping after an error. From the CLI, use `benchup call --live agent_activity '{"phase":"analyzing"}'` (and likewise for the other phases). Send each report as a call of its own, not inside a batch, where it is skipped. Activity reports change no model data, selection, or undo history; they are live-only, so `benchup tools` marks `agent_activity` with `live_only`. - Each changing call, and each batch, is one undo step labelled `Agent: …` in BenchUp's history. Prefer one batch per change, so the designer can undo it in one step. - Every call starts in the scope the designer is in. Put `enter_object` and the calls that need it in one batch, ending with `exit_to_root`. - `get_selection` is what the designer has selected: when they say "this" or "these", read it first. What you create or change is selected afterwards. @@ -57,7 +57,7 @@ Each other call is saved on its own, so prefer `run_batch` for any change of mor - Every board is a group. Editing tools (`move`, `resize_board`, `rename`, `tag`, `erase`, `add_joint`, `push_pull`…) reach parts inside groups and components by themselves when all the ids in a call share one group. Ids from different groups need separate calls. - To **create** a part inside a group, open it with `enter_object` (nested groups from the outside in). With the CLI, the opened group lasts only for that command, so put `enter_object` and the creating calls in one `--batch` and finish with `exit_to_root`. -- `group` with several ids makes ONE group, or one component with `component: true`. With one board and `component: true`, it wraps that board in a new component. Grouping keeps existing joints. Two components with the same name are still different definitions; only `create_copy` makes linked instances. +- `group` with several ids makes ONE group, or one component with `component: true`. With one board and `component: true`, it wraps that board in a new component. Grouping keeps existing joints, but it can change the ids of the parts it wraps (its result lists the new ones), so `tag` and `rename` parts before grouping them in the same batch. When organising a piece into modules, a part shared by two modules (a centre divider) stays outside both unless the user says where it goes. Grouping component instances keeps them linked. Two components with the same name are still different definitions; only `create_copy` makes linked instances. - Components suit identical parts whose joints stay inside them, such as a drawer box. Build one completely, including its joints, make it a component, then `create_copy` it to each position. Instances of one component share a `definition` id in the scene. - A joint can only be added between boards at the same level. A board inside a component instance cannot be joined to a board outside it. Making a board that already has joints into a component keeps those joints, but `create_copy` does not copy joints with boards outside the component, and they cannot be added to the copies. - **When the user asks for housed parts to be one component** (shelves in grooves in the sides), it cannot keep the grooves. By default keep them as separate identical boards, with the same name and tag, and say why. Offer the alternative: one component of shelves resting on pins or cleats, without joints to the sides. @@ -82,7 +82,7 @@ A joint joins two boards that **overlap** where they meet; the overlap is the jo | Shelf housed in a side | Shelf enters the side by about half the side's thickness (9 mm into 18) | `tongue_groove`, a = shelf, b = side | | Apron into a leg | Apron enters the leg 25 to 35 mm, set back 5 to 10 mm from the leg's outer face | `mortise_tenon`, a = apron, b = leg, `width_ratio` about 0.33 (tenon one third of the apron's thickness), `height_ratio` about 0.75 | | Back panel in a groove | Back (6 mm) enters each side by about half the side's thickness, 6 to 10 mm in from the back edge | `tongue_groove`, a = back, b = side | -| Back panel in a rabbet | Back enters each side by about half the side's thickness, flush with the back edge. Stop housed shelves 2 mm short of it (see below) | `rabbet`, a = back, b = side. This cuts both parts: a tongue on the back's edge (its front `width_ratio` share) in a slot in the side, leaving a lip of the side behind the back. For a classic open rabbet with the back left whole, rout it instead: `add_profile` `rabbet` on each side's back inner edge (`[["+y", "+x"]]` on the left side), as wide as the back is thick and half the side deep, with the back sitting in it and no joint | +| Back panel in a rabbet | Back enters each side by about half the side's thickness, flush with the back edge. Stop housed shelves 2 mm short of it (see below) | For the classic open rabbet with the back left whole, rout it: `add_profile` `rabbet` on each side's back inner edge (`[["+y", "+x"]]` on the left side, `[["+y", "-x"]]` on the right), as wide as the back is thick and half the side deep, with the back sitting in it and no joint. The `rabbet` joint kind (a = back, b = side) is something else: it cuts a tongue on the back's edge (its front `width_ratio` share) into a slot in the side, leaving a lip of the side behind the back | | Drawer side into the front (half-blind dovetail) | Side enters the front from behind, leaving 4 to 6 mm of the front | `dovetail`, a = drawer side, b = front, `dovetails` 3 to 5 | | Drawer bottom | Bottom (6 mm) enters the drawer sides by 6 mm and stops 1 to 2 mm behind the front, clear of the dovetails | `tongue_groove`, a = bottom, b = side | | Drawer back | Back (12 to 15 mm) enters the drawer sides by half their thickness, standing on the bottom | `tongue_groove` (a dado), a = back, b = side. Sitting on the bottom is fine: its dado and the bottom's groove only touch along the bottom's face. If the joint is refused, raise the back 1 mm | @@ -105,19 +105,19 @@ Two joints cut into the same board must not cross, and must not meet face to fac - **Carcass (cabinet, bookcase):** two sides, a top and a bottom (between the sides, or the top over them), shelves, and a back in a groove. Stop everything inside 1 to 2 mm short of the back. - **Even shelves:** `distribute` the shelves along z between the inner bottom and the inner top (`from_mm`, `to_mm`; without a bottom or top, the floor and the top of the sides, as the original spacing shows); the gaps above, below and between are equal, (H - n·t)/(n + 1), and the result reports `gap_mm`. Use `"mode": "centers"` for equal centre spacing. To change the number of shelves, erase or copy shelves, then `distribute` them again; their joints follow. With several columns, distribute each column in its own call. Check the clear height between two shelves with `measure_space` at a point between them. -- **Plinth:** a board 60 to 100 mm high between the sides, set back 20 to 50 mm from the front, usually under a bottom panel resting on it. A divider that reaches the floor splits it in two; butt each half against the divider. +- **Plinth:** a board 60 to 100 mm high between the sides, set back 20 to 50 mm from the front, usually under a bottom panel resting on it. A divider that reaches the floor splits it in two; butt each half against the divider. If the carcass has no bottom panel, the plinth is only a kick board: build it, and say so and ask whether to add a bottom. - **A back behind a central divider:** stop the divider at the back's front face so one back runs behind both bays. - **Edge profiles:** `add_profile` routs a chamfer, bevel, roundover, cove, rabbet, groove, ogee or bead along a board's edges with BenchUp's Router. Name an edge by the two faces it lies between: `[["+z", "-y"]]` is the top front edge, `[["+z", "*"]]` every edge of the top face, `[["-y", "-x"]]` the front vertical edge on the left (a corner seen from above); face ids from `get_object` work too. `width_mm` is the width or radius. For a rabbet or groove, which face gets the width and which the depth depends on the edge: check it in a dry run (the part that should sit in the rabbet shows as an overlap in `check_model` if it went the wrong way) and pass `reverse: true` to swap them. The call fails when the profile cannot be cut (too big, or an edge next to a notch); try a smaller size or other edges. `get_object` lists a board's profiles; `remove_profile` takes them off. - **A top with chamfered or rounded front corners over the sides:** let the top overhang the sides at the front by at least the chamfer, or set the sides back, so their corners do not show under the cut. - **Table:** legs 60 to 80 mm square; aprons 80 to 120 mm high and 20 to 25 mm thick, their tops flush with the legs, tenons as above; a top 25 to 40 mm thick resting on the frame with a 20 to 50 mm overhang. Ask whether the size given is the top or the frame, and whether the height includes the top. -- **Drawer:** build one drawer as a component (front, sides, back, bottom and their joints), then `create_copy` it up by the front's height plus the gap. Inset fronts leave about 2 mm at each side and 3 to 4 mm between drawers. The box (sides, back and bottom) has sides 12 to 15 mm thick and 30 to 50 mm lower than the front, and is 10 to 20 mm shorter than the carcass's inner depth. The bottom is 6 mm, grooved into the sides about 10 mm above their lower edge, and the back sits on the bottom. With metal runners, make the box about 12.5 mm narrower on each side, or as the runner specifies; with wooden runners, about 2 mm. -- **Lengthening a piece:** `resize_board` the boards that run in that direction, choosing the end with `anchor`, and `move` the parts at that end. `resize_board` stretches the whole board, notches included. For a board with notches or a shape, `push_pull` its end face by the extra length instead; that keeps the notches where they are. To push only part of a face, `split_face` it first, by a `line_mm` across it or where a `plane` crosses it; the result lists the pieces with their `center_mm` and area. Afterwards, `merge_faces` on the board removes seams between flat faces in one plane, also around an opening such as a pocket's mouth. Do not `erase` seam edges: erasing an edge removes the faces on it. A pocket or mortise cut by hand in the middle of a face is cleaner drawn than split: `enter_object` the board, draw the mouth as a closed `draw_polyline` inside the face (not touching its edges), and `push_pull` that face in; `split_face` planes cross the whole face and leave seams to merge. A joint with `add_joint` is better still when another board goes into it. +- **Drawer:** build one drawer as a component (front, sides, back, bottom and their joints), then `create_copy` it up by the front's height plus the gap. Inset fronts leave about 2 mm at each side and 3 to 4 mm between drawers. The box (sides, back and bottom) has sides 12 to 15 mm thick and 30 to 50 mm lower than the front, and is 10 to 20 mm shorter than the carcass's inner depth. The bottom is 6 mm, grooved into the sides about 10 mm above their lower edge, and the back sits on the bottom. With metal runners, make the box about 12.5 mm narrower on each side, or as the runner specifies; with wooden runners, about 2 mm. Wooden runners are strips (about 12 × 20 mm) on the inside of the carcass sides, one under each drawer side; they are separate boards butted against the sides, since a joint cannot reach from a part inside the drawer component to the carcass. For N equal inset drawers, each front is (opening height − gaps) / N, with the gaps above, below and between the fronts. +- **Lengthening a piece:** `resize_board` the boards that run in that direction, choosing the end with `anchor`, and `move` the parts at that end. `resize_board` stretches the whole board, notches included. For a board with notches or a shape, `push_pull` its end face by the extra length instead; that keeps the notches where they are. When the end face borders a notch (a top notched around a post), `push_pull` only extends that face's width and stretches the notch's face beside it: to keep the full width past the notch, `split_face` the new side face at the notch line and `push_pull` the outer piece out by the notch's depth, then `merge_faces`. To push only part of a face, `split_face` it first, by a `line_mm` across it or where a `plane` crosses it; the result lists the pieces with their `center_mm` and area. Afterwards, `merge_faces` on the board removes seams between flat faces in one plane, also around an opening such as a pocket's mouth. Do not `erase` seam edges: erasing an edge removes the faces on it. A pocket or mortise cut by hand in the middle of a face is cleaner drawn than split: `enter_object` the board, draw the mouth as a closed `draw_polyline` inside the face (not touching its edges), and `push_pull` that face in; `split_face` planes cross the whole face and leave seams to merge. A joint with `add_joint` is better still when another board goes into it. - **Before choosing which end to lengthen,** look for walls and other parts in the way. `measure_space` at a point gives the free distance along each axis to the nearest face and what it belongs to, walls made of plain faces included. `find_surfaces` lists large flat faces that are not boards, such as a room's walls and floor drawn as faces inside groups, with their plane (`y = 400`); `include_solids` adds faces of closed parts, such as a solid floor. - **Changing the stock thickness while keeping the outside size:** `change_thickness` the boards in one call, with the new material in `material_id`. Boards on the outside of the given set keep their outer face, the others their centre; boards that go into a resized board with a joint are lengthened or shortened so the joint keeps the same share of the new thickness (half stays half), and boards that only butt against a resized board (shelves against a divider) follow its face. `anchor` applies to every board of the call: call it twice for different anchors. Pass `"anchor": "min"` to keep whole millimetres on shelves when an odd change would give half millimetres. Recompute equal gaps only if asked (`distribute`). `check_model` reports boards whose thickness does not match their material. For rotated boards, use `resize_board` with `anchor` instead. - **A leaning piece (ladder shelf):** work out each upright's outline as it will stand: back edge leaning θ from vertical and touching the wall at the top, foot and top cut level. Rotate that outline by +θ about x around the foot of its back edge, which stands it upright, and draw it there (see shaped boards). Set its grain to z, then `rotate` it by −θ about x around the same point, so its top leans towards the wall at +Y. An upright of constant width w (measured square to its edges) and height H has edges H/cos θ long and level cuts w/cos θ long, and the foot of its back edge sits H·tan θ from the wall. Uprights of constant width give every shelf the same depth. For shelves that get shallower towards the top, taper the uprights (wider at the foot), or let the shelves stick out in front of narrow uprights. Keep shelf edges a few millimetres away from the uprights' sloping faces; a near-coincident edge leaves slivers smaller than the model precision. In the scene, a rotated board's grain shows as a vector, and the cut list measures it unrotated. - **Materials and cut list:** `create_stock_material` (name, thickness, width, length; the length along the grain), then `set_material` on the boards. The material's thickness should match the boards'. `get_cut_list` groups boards by material and size; `minimum_stock_pieces`, an area lower bound, appears once boards have a material with sizes. To answer "how many sheets do I need" without changing the project, create and assign the material and call `get_cut_list` in one `--dry-run` batch. - **Finishes and time:** `set_finish` on boards or a whole group: `sanding_grits` ([120, 180, 240]) and the `pre_stain`, `stain` and `varnish` stages with their coats, drying hours and look (`tint_rgb`, `sheen`). `get_estimate` (all boards, or `ids`) adds up finishing time per stage from each board's area, joint cutting by kind and router profiles by length, with BenchUp's default allowances, and lists the wood by material. Rates and prices edited in the app are not in the project, so it gives no costs. -- **Dimensions for the workshop:** put overall height and width, and a chain of shelf gaps, in the front plane (y = 0) so they read in the front view; put the depth in the side plane (x = the width), offset upwards. A dimension measures the straight distance between its points. Pass `axis` to measure only along x, y or z, so a slightly misplaced point cannot tilt it. Points exactly on a corner, edge or face attach to it and follow it. Nothing snaps, so use real corners: where a shelf enters a side, its visible corner is on the side's inner face. `offset_mm` pushes the line away from the piece: chain dimensions about 100 mm out, overall ones about 250 mm out, so they do not overlap. `add_dimension` returns `length_mm`, and `get_scene` lists every dimension. Put the piece's name in a text above it. Ask whether shelf spacing means clear space or centre to centre. +- **Dimensions for the workshop:** put overall height and width, and a chain of shelf gaps, in the front plane (y = 0) so they read in the front view; put the depth in the side plane (x = the width), offset upwards. A dimension measures the straight distance between its points. Pass `axis` to measure only along x, y or z, so a slightly misplaced point cannot tilt it. Points exactly on a corner, edge or face attach to it and follow it. Nothing snaps, so use real corners: where a shelf enters a side, its visible corner is on the side's inner face. `offset_mm` pushes the line away from the piece: chain dimensions about 100 mm out, overall ones about 250 mm out, so they do not overlap. With `axis`, the line goes through the midpoint of the two points before the offset, so on a leaning or stepped piece measure the offset from that midpoint. `add_dimension` returns `length_mm`, and `get_scene` lists every dimension. Put the piece's name in a text above it. Ask whether shelf spacing means clear space or centre to centre. ## Shaped boards (curves, chamfers, angled ends) diff --git a/docs/cli.md b/docs/cli.md index 6a179ce..fd31d2d 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -131,7 +131,7 @@ How it behaves: - **Scope and selection:** every call starts in the scope the designer is in, so put `enter_object` and the calls that need it in one batch. The agent sees the designer's selection (`get_selection`), so the designer can say "change this". - **Project switches:** every result names the open project. A call that was waiting when another project was opened is refused, so the agent can look again with `get_scene`. A collaborator's new revision of the same shared project does not refuse waiting calls. - **Timeouts and size:** a call waits up to 15 seconds for BenchUp to connect and up to 120 seconds for its answer, then fails with a hint. A call larger than 16 MB is refused by the bridge; split it into smaller batches. An answer larger than 32 MB comes back as an error (with `applied: true` when the call still changed the model); filter `get_scene` or render a smaller view. -- **Security:** only programs that know the token can use the bridge, and the token is never sent: both sides prove they know it with a challenge-response (HMAC-SHA256 over fresh nonces). Browsers must come from `https://benchup3d.github.io` or a local development server (`--allow-origin` adds another), so other web pages cannot reach it. Pass the token in the environment, never as a command-line argument, which other users on the computer can see. +- **Security:** only programs that know the token can use the bridge, and the token is never sent: both sides prove they know it with a challenge-response (HMAC-SHA256 over fresh nonces). Browsers must come from the published web app (`https://benchup3d.github.io`, which redirects to `https://benchup.io`) or a local development server (`--allow-origin` adds another), so other web pages cannot reach it. Pass the token in the environment, never as a command-line argument, which other users on the computer can see. - **Web browsers:** Chrome and Safari may ask whether the site may connect to devices on your local network the first time BenchUp connects to the bridge; allow it. ## Using it from an agent