Official Codebase of 3DCodeVerse
Python
tools: close the review of the verdict/failed split — and bound the payload
ziyao933b8ecc6dee
diff --git a/harness/codeverse/spatial/mcp_server.py b/harness/codeverse/spatial/mcp_server.pyindex e7d474a5..784eec95 100644--- a/harness/codeverse/spatial/mcp_server.py+++ b/harness/codeverse/spatial/mcp_server.py@@ -8,6 +8,9 @@ observation text (+ compact numbers when small) and one ``ImageContent`` perobservation image (base64 PNG, long side ≤ 1024 px, at most ``MAX_IMAGES``).``is_error`` is ``Observation.failed`` (the tool could not run) — never anegative verdict, which is an ordinary result whose text leads with FAIL.+Every result is bounded here — ``MAX_TEXT_CHARS`` of text and a per-outcome image+budget (:func:`max_images_for`) — because this is the last place the harness owns+before the payload becomes the vendor's prompt.Track / language default to ``<ws>/spec.json`` so agents need no flags."""@@ -24,7 +27,7 @@ from typing import Anyfrom PIL import Image-from codeverse.spatial.observe import fmt_numbers+from codeverse.spatial.observe import fmt_numbers, truncatefrom codeverse.spatial.registry import Observation, ToolContext, list_toolsfrom codeverse.spatial.tool_common import spec_dictfrom codeverse.workspace import Workspace@@ -32,6 +35,11 @@ from codeverse.workspace import WorkspaceMAX_IMAGES = 4MAX_IMAGE_SIDE = 1024MAX_NUMBERS_CHARS = 1200+#: hard ceiling on the text block of ONE result (text + numbers), twice the largest+#: per-tool limit in ``observe`` — an Observation built by hand (``joint_sweep``,+#: ``compare_reference``) never goes through those, and nothing may hand the model an+#: unbounded payload from here.+MAX_TEXT_CHARS = 6000SERVER_NAME = "3dcv"@@ -59,16 +67,34 @@ def encode_image(path: str, max_side: int = MAX_IMAGE_SIDE) -> str | None:return base64.b64encode(buf.getvalue()).decode("ascii")+def max_images_for(obs: Observation) -> int:+ """Image budget for ONE result, by outcome — the guard on the error path.++ A vendor CLI that receives ``is_error`` stringifies the WHOLE result, image parts+ included: gemini-cli's error branch prints ``safeJsonStringify(rawResponseParts)``,+ so a 275 kB contact sheet arrives as ~366 k characters of base64 TEXT (~261 k prompt+ tokens) instead of ~516 as an inline image, and its own 40 000-char truncation does+ not fire for a multi-part MCP result (docs/COST.md §30). So a failed observation+ ships no image (nothing rendered is evidence about a tool that could not run), and a+ FAIL verdict ships one — the sheet, which ``image_budget`` keeps first.+ """+ if obs.failed:+ return 0+ return MAX_IMAGES if obs.ok else 1++def observation_content(obs: Observation) -> list[Any]:- """Observation → MCP content blocks (text first, then images)."""+ """Observation → MCP content blocks (text first, then images), both bounded."""from mcp import typestext = obs.textif obs.numbers:nums = json.dumps(obs.numbers, default=str)text += "\n" + (nums if len(nums) <= MAX_NUMBERS_CHARS else fmt_numbers(obs.numbers))- blocks: list[Any] = [types.TextContent(type="text", text=text)]- for p in obs.images[:MAX_IMAGES]:+ # the slice makes the ceiling hard: truncate's "N chars omitted" marker overshoots its+ # own budget by a few characters, and this is the last bound before the vendor's prompt+ blocks: list[Any] = [types.TextContent(type="text", text=truncate(text, MAX_TEXT_CHARS)[:MAX_TEXT_CHARS])]+ for p in obs.images[:max_images_for(obs)]:b64 = encode_image(p)if b64:blocks.append(types.ImageContent(type="image", data=b64, mime_type="image/png"))@@ -93,8 +119,9 @@ def make_server(ctx: ToolContext):return types.CallToolResult(content=[types.TextContent(type="text", text=f"unknown tool {params.name!r}; known: {sorted(defs)}")], is_error=True)obs = await asyncio.to_thread(tdef.call, ctx, params.arguments or {})# is_error is Observation.failed, NOT `not ok`: a tool that RAN and answered FAIL- # is a result the model must read, and an MCP error is a call it retries instead- # (~117k prompt tokens a retry). The FAIL verdict leads the text.+ # is a result the model must read, and an MCP error is a call the vendor retries+ # instead (a mean 119k prompt tokens, $0.030 blended) — and, on gemini-cli, one+ # whose images it re-sends as base64 TEXT. The FAIL verdict leads the text.return types.CallToolResult(content=observation_content(obs), is_error=obs.failed)return Server(SERVER_NAME, version="0.1.0",diff --git a/harness/codeverse/spatial/observe.py b/harness/codeverse/spatial/observe.pyindex 0ba5470b..44ffccf4 100644--- a/harness/codeverse/spatial/observe.py+++ b/harness/codeverse/spatial/observe.py@@ -197,13 +197,34 @@ def gate_observation(report: GateReport, *, title: str = "", max_findings: int =def render_observation(rs: RenderSet, root: Path, *, note: str = "", max_individual: int = 4) -> Observation:- """Contact sheet first, individual views when few; text lists views + cameras."""+ """Contact sheet first, individual views when few; text lists views + cameras.++ The negative outcomes are NOT one answer. **Console errors** are a verdict+ (``ok=False``, ``failed=False``) whether or not any view came back: the scene ran+ far enough to log them and the agent fixes them in ``src/`` — a scene that fails to+ boot returns an empty RenderSet whose ``console_errors`` say why (``render_scene``),+ and reporting that as a broken call would buy a blind retry of the very thing that+ just explained itself. **No views and nothing logged** is a failure+ (``failed=True``): the tool's product is pictures, it has none and no reason, and+ nothing the agent edits changes that. Either way the verdict leads the text, since+ a negative verdict now only reaches the model as text.+ """images: list[str] = []if rs.contact_sheet:images.append(rs.contact_sheet)if len(rs.views) <= max_individual:images.extend(v.path for v in rs.views)- lines = [note] if note else []+ lines: list[str] = []+ if rs.console_errors:+ lines.append(f"RENDER: FAIL — {len(rs.console_errors)} console error(s)"+ + (" and no view rendered; the errors below say why" if not rs.views+ else "; the views below rendered anyway"))+ elif not rs.views:+ lines.append("RENDER PRODUCED NO VIEWS" + (f" ({rs.renderer})" if rs.renderer else "")+ + " — nothing to look at and nothing logged: the renderer failed, "+ "there is no finding here to fix in src/")+ if note:+ lines.append(note)lines.append(f"{len(rs.views)} view(s)" + (f" via {rs.renderer}" if rs.renderer else "") + (", contact sheet first" if rs.contact_sheet else ""))for v in rs.views:cam = ""@@ -223,5 +244,6 @@ def render_observation(rs: RenderSet, root: Path, *, note: str = "", max_individnumbers["fps"] = rs.fpsif rs.console_errors:numbers["console_errors"] = len(rs.console_errors)- return Observation(ok=not rs.console_errors, text=truncate("\n".join(lines)), numbers=numbers,- images=image_budget(images))+ return Observation(ok=bool(rs.views) and not rs.console_errors,+ failed=not rs.views and not rs.console_errors,+ text=truncate("\n".join(lines)), numbers=numbers, images=image_budget(images))diff --git a/harness/codeverse/spatial/registry.py b/harness/codeverse/spatial/registry.pyindex 5d9fc7e3..2338df15 100644--- a/harness/codeverse/spatial/registry.py+++ b/harness/codeverse/spatial/registry.py@@ -39,11 +39,12 @@ class Observation(BaseModel):nothing penetrates); ``failed`` says the tool could not run at all.Only ``failed`` becomes MCP ``is_error`` (``spatial.mcp_server``). Measured over- 217 recorded gemini-cli sessions: with ``is_error = not ok``, 63% of 1404- joint_sweep calls, 23% of 2073 builds and ~15% of the connectivity/contract calls- reached the model as broken calls, and the model retries a broken call — ~117k- prompt tokens ≈ $0.034 each. A negative verdict is a result: it keeps- ``failed=False`` and leads its ``text`` with the FAIL verdict instead.+ 224 recorded gemini-cli sessions (selector + full table in docs/COST.md §30): with+ ``is_error = not ok``, 62% of 1445 joint_sweep calls, 23% of 2144 builds and ~15%+ of the connectivity/contract calls reached the model as broken calls, and the model+ retries a broken call — a mean 119k prompt tokens, $0.030 at the measured 73% cache+ hit rate. A negative verdict is a result: it keeps ``failed=False`` and leads its+ ``text`` with the FAIL verdict instead."""ok: bool = True@@ -56,7 +57,17 @@ class Observation(BaseModel):@classmethoddef error(cls, text: str, **numbers: Any) -> Observation:- """The tool could not run — the ONE constructor for a genuine failure."""+ """The tool could not run: every failure caught at the :meth:`ToolDef.call`+ boundary and every missing / unreadable artefact is built here.++ It is not the only thing that sets ``failed``. Three results are failures+ the tool computed rather than exceptions it caught, and they set the flag on+ an observation they compose themselves: ``build`` (the runtime reported+ success and left no readable GLB), ``scene_probe`` (the probe driver died)+ and ``observe.render_observation`` (no view AND no console error — with one+ it is a verdict). Those four places are the whole list; nothing else may set+ ``failed``.+ """return cls(ok=False, failed=True, text=text, numbers=numbers)diff --git a/harness/codeverse/spatial/tools.py b/harness/codeverse/spatial/tools.pyindex 2a23e71a..2b810b44 100644--- a/harness/codeverse/spatial/tools.py+++ b/harness/codeverse/spatial/tools.py@@ -469,7 +469,7 @@ def _sweep_verdict(report: SweepReport) -> tuple[bool, str]:"""(passed, headline) of a collision sweep — the ONE place that decides both.The headline leads the observation because a sweep that finds a penetration is a- RESULT, not a tool error (63% of 1404 recorded joint_sweep calls answered FAIL):+ RESULT, not a tool error (62% of 1445 recorded joint_sweep calls answered FAIL):without it the model reads 'pose sweep: 12 poses…' and has to infer the verdict."""s = report.summarydiff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex 6875f981..a00c1dbc 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -337,12 +337,19 @@ server (name `3dcv`) for the vendor CLIs, (c) a native tool schema for any embed`gl_probe`, `gl_frames` (graphics), `texture_pass`, `texture_preview` (object tracks).An `Observation` carries two different answers: `ok` is the **verdict** and `failed`-says the tool **could not run** (exception, missing artefact, unusable arguments —-`Observation.error` is the only constructor that sets it). MCP `is_error` is `failed`-alone: a negative verdict is a result whose text leads with FAIL, because a vendor CLI-retries an errored call, and over 217 recorded gemini-cli sessions `is_error = not ok`-made 63 % of 1 404 `joint_sweep` calls, 23 % of 2 073 `build`s and ~15 % of the-connectivity/contract calls look broken (~117 k prompt tokens ≈ $0.034 a retry).+says the tool **could not run** (exception, missing artefact, unusable arguments).+`Observation.error` builds every failure caught at the `ToolDef.call` boundary; three+tools set `failed` on an observation they compose themselves, where the failure is a+fact about the result rather than an exception — `build` (runtime success, no readable+GLB), `scene_probe` (the probe driver died) and `observe.render_observation` (no view AND+no console error; with one it is a verdict). Those four places are the whole list. MCP `is_error` is `failed` alone: a+negative verdict is a result whose text leads with FAIL, because a vendor CLI retries an+errored call, and over 224 recorded gemini-cli sessions `is_error = not ok` made 62 % of+1 445 `joint_sweep` calls, 23 % of 2 144 `build`s and ~15 % of the connectivity/contract+calls look broken (a mean 119 k prompt tokens ≈ $0.030 blended a retry — docs/COST.md §30+for the selector, and for what an errored result costs when it carries an image).+The MCP server also bounds every payload it hands over (`MAX_TEXT_CHARS`,+`max_images_for`): no image at all on a `failed` result, one on a FAIL verdict.## 6. Judging (protocol v2)diff --git a/harness/docs/COST.md b/harness/docs/COST.mdindex f5182428..43074d2c 100644--- a/harness/docs/COST.md+++ b/harness/docs/COST.md@@ -1378,29 +1378,106 @@ come from.`spatial/mcp_server.py` returned `is_error = not obs.ok`, and `obs.ok` was the tool's**verdict** — so every gate that ran and answered FAIL reached the model as a broken call.-From the tool stats of 217 recorded gemini-cli sessions (`run/trajectories/*/stdout.json`):++**Selector** (every number in this section, unless another one is named): the files+`bench/out/*/**/run/trajectories/*/stdout.json`, 386 of them, of which **224 are+non-empty** — one per gemini-cli session that reported stats; the other 162 are+zero-byte (the CLI died or was killed before printing its JSON) and every one of the+386 belongs to a gemini-cli arm. `run/telemetry/trajectories` is a symlink to the same directory:+count it once (a glob that follows it doubles every number). Per file, sum+`stats.tools.byName["mcp_3dcv_<tool>"]`'s `count` and `fail`; `fail` is gemini-cli's+own tally of results that arrived with `is_error`. Over those 224 sessions: **6 127+MCP tool calls, 1 720 (28 %) reported as errors.**| tool | calls | reported as an error | the harness's own gate, for comparison ||---|---|---|---|-| `joint_sweep` | 1 404 | 63 % | end-of-round sweep gate fails 16 % of 243 rounds |-| `build` | 2 073 | 23 % | — (a build that does not compile IS the answer) |-| `check_contract` | 877 | 16 % | — |-| `check_connectivity` | 888 | 15 % | — |--A vendor CLI treats an errored tool call as a call that did not happen and retries it; a-retried request carries the whole session context, ~117 000 prompt tokens ≈ **$0.034**.--The fix is a second flag, not a threshold: `Observation.failed` (set only by-`Observation.error` — exception, missing artefact, unusable arguments, `ToolUnavailable` /-`ToolUsageError`) is what the MCP server reports as `is_error`; `ok` stays the verdict, and-every negative verdict now LEADS its text with `… FAIL` (`gate_observation` for the gates,-`JOINT SWEEP: FAIL — penetration …`, `FRAME GATE: FAIL — …`, `BUILD FAILED` as before) so the-model reads the answer instead of retrying the question.--What to watch on the next battery: in `tools stats`, `joint_sweep` / `build` /-`check_*` error counts → near zero (only genuine failures — no URDF, unreadable GLB,-bad arguments), calls per run down by the retries that used to follow each of them, and-`telemetry/cost.jsonl` prompt tokens per session down accordingly. The 63 % vs 16 % gap-between the sweep TOOL's verdict and the round's sweep GATE is a separate question — the tool-flags any overlap past `tol_m` and any floating link, while `sweep_findings` downgrades small-rest overlaps and hinge gaps to WARN.+| `joint_sweep` | 1 445 | 62 % | the round's `joint_sweep` GATE fails 57 of the 299 rounds that ran it (19 %) |+| `build` | 2 144 | 23 % | — (a build that does not compile IS the answer) |+| `check_contract` | 895 | 17 % | — |+| `check_connectivity` | 923 | 14 % | — |+| `isolate` | 35 | 49 % | — (these ARE mostly real usage errors: an unknown part name) |++(The gate column is a second selector: all 239 `run/record.json` under `bench/out/`,+411 rounds. An earlier draft of this section quoted 217 sessions / 1 404 sweeps / 63 %+— that was the same corpus minus the `.attempt1` retry sessions and did not reproduce;+these numbers do, with the glob above.)++A vendor CLI treats an errored tool call as a call that did not happen and retries it.+A retried request carries the whole session context: **a mean 118 700 prompt tokens**+(9 250 main-role requests over the 224 sessions), 73 % of them cache hits, so+**$0.030 per retry** at `gemini-3.7-flash`'s $0.75/M input + $0.075/M cached — a+*cache-blended* rate, not the list price ($0.089 at full input rate), and ~$0.040 with+the response the retry also pays for.++### The expensive half: an errored result re-sends its images as TEXT++An independent offline investigation of the recorded requests (its own selector: the+per-request logs, not the session stats above) found the retry is not the main bill.+`observation_content` attaches PNGs as MCP `ImageContent`. On the success path+gemini-cli calls `transformMcpContentToParts` and sends a real `inlineData` part; on the+**error** path (bundle `chunk-DFPYJMVX.js:274288`) it builds+`"MCP tool '<name>' reported tool error ... with response: " + safeJsonStringify(rawResponseParts)`+— the image's base64 goes into the prompt as text:++| the same articulation contact sheet | bytes / chars | prompt tokens |+|---|---|---|+| `inlineData` part (success path) | 274 572 B | ≈ 516 |+| base64 inside an error string (error path) | 366 096 chars | ≈ 261 497 (**~507×**) |++It also escapes gemini-cli's own 40 000-char truncation (bundle `:349408`), which only+fires for a single-text-part MCP result or the shell tool. The predicted jump matches+recorded per-request prompt jumps of +260 421, +256 907, +258 997, +257 840, +260 364 and++261 477 tokens. ~10 % of requests carried ~225 000 freshly *uncacheable* tokens, and that+10 % is **67 % of the whole uncached bill (~$400 of $873)** on the corpus it measured.+Non-blob requests already cache as well as the old in-process agent did (median 4 946+uncached tokens vs 5 639 per turn), so nothing about settings, tool ordering or `GEMINI.md`+needs changing — the blob is the whole anomaly.++`joint_sweep` is exactly where the two findings meet: it always attaches the articulation+contact sheet, and 900 of its 1 445 calls were errors. Corroboration inside the session+stats above: the 205 sessions with ≥ 1 errored `joint_sweep` have a 73 % cache-hit rate and+a median session averaging 106 250 prompt tokens per request, against 88 % and 78 349 for+the 19 without (confounded — those are also the articulated runs — but it points the same way).++### The fix++A second flag, not a threshold. `Observation.failed` is what the MCP server reports as+`is_error`; `ok` stays the verdict. `Observation.error` builds every failure caught at the+`ToolDef.call` boundary (exception, `ToolUnavailable`, `ToolUsageError`, missing or+unreadable artefact), and three tools set `failed` on a result they compose themselves,+where the failure is a fact about the result rather than an exception: `build` (the runtime+reported success and left no readable GLB), `scene_probe` (the probe driver died) and+`observe.render_observation` (no view AND nothing logged — a render with no picture and no+reason is not a verdict; console errors ARE one, empty RenderSet or not, because a scene+that fails to boot returns exactly that and the errors say what to fix). Those four places+are the whole list.++Every negative verdict now LEADS its text with `… FAIL` (`gate_observation` for the gates,+`JOINT SWEEP: FAIL — penetration …`, `FRAME GATE: FAIL — n error(s)`, `RENDER: FAIL — n+console error(s)`, `BUILD FAILED` as before) so the model reads the answer instead of+retrying the question.++And because the harness now decides what is an error, `mcp_server` bounds what one result+can hand over: `MAX_TEXT_CHARS` = 6 000 characters of text (twice the largest per-tool+limit — an Observation built by hand never passes through `observe`'s truncation), and+`max_images_for`: 4 images on an `ok` result, **1** on a FAIL verdict, **0** on a `failed`+one. The vendor's own 40 000-char guard does not fire for a multi-part result, so this is+the only ceiling on the error path.++### Exit codes DID change for one command++`3dcv tools <name>` exits 1 on `not obs.ok` — the rule is unchanged, but `scene_probe`'s+`ok` changed meaning (it used to mean "the probe tool ran", the workaround for this bug),+so **`3dcv tools scene_probe` on a failing scene gate now exits 1 where it exited 0**.+Kept deliberately: every other gate tool already exited 1 on a FAIL, and the exit code+speaks to the human or script at the terminal, not to the model — the MCP boundary is the+one place where calling a verdict an error costs money. The CLI panel prints three states+(`ok` / `FAIL` / `error`) to match.++What to watch on the next battery: in `tools stats`, `joint_sweep` / `build` / `check_*`+error counts → near zero (only genuine failures — no URDF, unreadable GLB, bad arguments),+calls per run down by the retries that used to follow each of them, per-request prompt+tokens without the ~260 k spikes, and the uncached share of `telemetry/cost.jsonl` down+with them. The 62 % vs 19 % gap between the sweep TOOL's verdict and the round's sweep+GATE is a separate question — the tool flags any overlap past `tol_m` and any floating+link, while `sweep_findings` downgrades small rest overlaps and hinge gaps to WARN.diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex e409a5d4..a048640f 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -311,7 +311,11 @@ from codeverse.spatial.frame_stats import sequence_stats, frame_gate # gate "# static | flicker | low_detail | duplicate | no_framesfrom codeverse.spatial.registry import tool, get_tool, list_tools, tool_cards, ToolContext, ObservationObservation{ok: VERDICT, failed: the tool could not run, text, numbers, images, duration_ms} # is_error == failed,- # never `not ok`; Observation.error(...) is the ONE constructor that sets failed+ # never `not ok`. failed is set by Observation.error(...) and by exactly three tools that compose+ # their own result: build (no readable GLB), scene_probe (driver died), render_observation (no view+ # and no console error — with one it is a verdict)+from codeverse.spatial.mcp_server import observation_content, max_images_for, MAX_TEXT_CHARS+ # payload bound at the MCP boundary: text truncated; images 4 (ok) | 1 (FAIL verdict) | 0 (failed)import codeverse.spatial.tools # registers: build, measure, render_views, render_sheet, isolate, cross_section,# check_connectivity, check_contract, compare_silhouette, joint_sweep [articulated], shader_probe, scene_probe,# scene_views + check_placement [scene], gl_probe + gl_frames [graphics], texture_pass + texture_preview [object tracks]diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.mdindex c4bb679a..43f61ff3 100644--- a/harness/docs/RUNBOOK.md+++ b/harness/docs/RUNBOOK.md@@ -152,6 +152,9 @@ unless you type `--host` yourself; it never serves a path outside the declared r3dcv texture pass <slug> [--no-judge] [--model …] [--judge-model …] [--image-model …] [--size 1024]3dcv texture scene-pack <slug> [--n 10] · 3dcv texture show <slug>3dcv tools list [--cards] · 3dcv tools measure --workspace runs/<slug> · 3dcv tools gl_frames --workspace … --json '{"times":[0,1,2.5]}'+ # panel says ok | FAIL (the verdict) | error (the tool could not run);+ # exit 1 on either non-ok state — `scene_probe` included since 2026-09-02+ # (COST.md §30), where a failing scene gate used to exit 03dcv flywheel export runs/ dataset/ [--min-score 0.7] [--only-passed] [--pack] [--include-unbuilt][--captions-dir caps/] [--drop-duplicates]3dcv flywheel pairs runs/ pairs.jsonl [--min-delta 0.05]diff --git a/harness/tests/spatial_tools/test_mcp_server.py b/harness/tests/spatial_tools/test_mcp_server.pyindex a3f12329..4bfa23d0 100644--- a/harness/tests/spatial_tools/test_mcp_server.py+++ b/harness/tests/spatial_tools/test_mcp_server.py@@ -37,6 +37,33 @@ def test_observation_content_blocks(tmp_path: Path) -> None:assert encode_image(str(tmp_path / "missing.png")) is None+def test_result_payload_is_bounded_by_outcome(tmp_path: Path) -> None:+ """Since the harness decides what is an error, no single result may hand the model an+ unbounded blob. Text is capped here (an Observation built by hand never passes through+ ``observe``'s truncation), and the image budget shrinks with the outcome: gemini-cli's+ error path re-sends the WHOLE result as text, base64 images included — a 275 kB contact+ sheet arrives as ~261k prompt tokens instead of ~516 (docs/COST.md §30) — and its own+ 40 000-char truncation does not fire for a multi-part MCP result."""+ from PIL import Image++ from codeverse.spatial.mcp_server import MAX_TEXT_CHARS, max_images_for++ pngs = []+ for i in range(5):+ p = tmp_path / f"v{i}.png"+ Image.new("RGB", (32, 32), (10 * i, 0, 0)).save(p)+ pngs.append(str(p))+ huge = "x" * 200_000+ cases = ((Observation(ok=True, text=huge, images=pngs), 4),+ (Observation(ok=False, text=huge, images=pngs), 1), # a FAIL verdict+ (Observation(ok=False, failed=True, text=huge, images=pngs), 0)) # the tool could not run+ for obs, n_images in cases:+ assert max_images_for(obs) == n_images+ blocks = observation_content(obs)+ assert len(blocks[0].text) <= MAX_TEXT_CHARS+ assert sum(1 for b in blocks if b.type == "image") == n_images++def test_cli_list(stool_ctx: ToolContext, capsys: pytest.CaptureFixture[str]) -> None:assert main(["--workspace", str(stool_ctx.workspace.root), "--list"]) == 0data = json.loads(capsys.readouterr().out)diff --git a/harness/tests/spatial_tools/test_observe.py b/harness/tests/spatial_tools/test_observe.pyindex 7792da0e..cbe6ebfc 100644--- a/harness/tests/spatial_tools/test_observe.py+++ b/harness/tests/spatial_tools/test_observe.py@@ -73,6 +73,32 @@ def test_render_observation(tmp_path: Path) -> None:assert "cam=(0, 1, 2)" in obs.text+def test_render_with_no_views_is_a_failure_console_errors_are_a_verdict(tmp_path: Path) -> None:+ """The negative renders are not one answer. Nothing rendered and nothing logged: the+ tool's product is pictures, it has none and no reason, and nothing the agent edits+ changes that — an MCP error (``failed``). Console errors: the scene RAN far enough to+ log them, so it is a verdict the agent fixes, even when the boot failure left zero+ views (`render_scene` returns exactly that) — reporting THAT as a broken call buys a+ blind retry of the thing that just explained itself. Both lead the text."""+ empty = render_observation(RenderSet(views=[], renderer="fake"), tmp_path, note="shaded render")+ assert not empty.ok and empty.failed+ assert empty.text.startswith("RENDER PRODUCED NO VIEWS (fake)")+ assert empty.numbers["n_views"] == 0++ rs = RenderSet(views=[RenderView(name="front", path=str(tmp_path / "v.png"))], renderer="fake",+ console_errors=["TypeError: x is undefined"])+ obs = render_observation(rs, tmp_path, note="scene views")+ assert not obs.ok and not obs.failed+ assert obs.text.startswith("RENDER: FAIL — 1 console error(s); the views below rendered anyway")+ assert "scene views" in obs.text and "TypeError" in obs.text++ booted = render_observation(RenderSet(views=[], renderer="fake", console_errors=["SyntaxError: scene.js:12"]),+ tmp_path)+ assert not booted.ok and not booted.failed # the scene told the agent what to fix+ assert booted.text.startswith("RENDER: FAIL — 1 console error(s) and no view rendered")+ assert "SyntaxError" in booted.text++def test_lint_lines_split_by_severity(tmp_path: Path) -> None:rep = GateReport(gate="lint:x", passed=False, findings=[GateFinding(gate="lint:x", severity=Severity.ERROR, target=str(tmp_path / "src" / "a.py"), message="bad", fix_hint="fix it"),diff --git a/harness/tests/spatial_tools/test_tools.py b/harness/tests/spatial_tools/test_tools.pyindex 492ed9b6..b3dc9a27 100644--- a/harness/tests/spatial_tools/test_tools.py+++ b/harness/tests/spatial_tools/test_tools.py@@ -292,6 +292,18 @@ def test_render_views_cached(stool_ctx: ToolContext, fake_renderer) -> None:assert not obs.ok and "shaded" in obs.text and "failed" not in obs.text+def test_render_tool_with_no_view_is_a_tool_failure(stool_ctx: ToolContext, monkeypatch: pytest.MonkeyPatch) -> None:+ """A renderer that comes back with nothing left the agent no picture and no verdict:+ ``failed`` (an MCP error), not an ordinary result whose text happens to say '0 view(s)'."""+ import codeverse.spatial.render as render++ monkeypatch.setattr(render, "render_glb", lambda *a, **k: RenderSet(views=[], renderer="fake"))+ for name, args in (("render_views", {}), ("render_sheet", {}), ("isolate", {"part": "Leg_3"})):+ obs = get_tool(name).call(stool_ctx, args)+ assert not obs.ok and obs.failed, name+ assert obs.text.startswith("RENDER PRODUCED NO VIEWS"), name++def test_render_modes_match_the_js_rig() -> None:"""One mode tuple: contracts.RENDER_MODES ↔ runtime_js/render_glb.mjs MODES ↔ the arg schema."""import re@@ -432,6 +444,41 @@ def test_build_tool_graphics_reports_frames(tmp_ws: Workspace, monkeypatch: pyteassert not obs.ok and "static image" in obs.text+class _GlRuntime(_NoGlbRuntime):+ """Graphics runtime whose build takes the gl tools' kwargs (times / preview / size)."""++ def build(self, ws, **_kw):+ return BuildResult(ok=True, language=self.language, glb_path=None, duration_ms=9,+ census=self.census, extra_paths=self.extra_paths)+++def test_gl_tools_lead_with_the_frame_gate_verdict(tmp_ws: Workspace, monkeypatch: pytest.MonkeyPatch) -> None:+ """The shader compiled and the frames rendered, and the ``gl_frames`` gate still failed.+ All three tools that print an "… OK" headline over that gate (``build`` on a graphics+ workspace, ``gl_probe``, ``gl_frames``) must put the FAIL verdict ABOVE it — otherwise+ the only verdict the model reads is "PROBE OK" — and none of them is a tool failure:+ the code ran, and re-running it blind is exactly the retry this costs money."""+ import codeverse.languages._gl_common as gl_build # the one metrics reader+ from codeverse.spatial.frame_stats import FrameStat, SequenceStats++ ctx = ToolContext(workspace=tmp_ws, language="glsl_shader", track="graphics")+ _patch_runtime(monkeypatch, _GlRuntime("glsl_shader", {"renderer": "moderngl"}))+ stats = SequenceStats(frames=[FrameStat(time=0.0, path="f0.png", mean_lum=0.4, std_lum=0.2, pct_black=0.01,+ pct_blown=0.01, colourfulness=0.3, edge_density=0.05)], mean_diff=0.0)+ bad = GateReport(gate="gl_frames", passed=False, findings=[+ GateFinding(gate="gl_frames", severity=Severity.ERROR, message="static image", data={"kind": "static"},+ fix_hint="animate with u_time")])+ monkeypatch.setattr(gl_build, "read_metrics", lambda ws: (stats, bad))+ for name, args, ok_headline in (("build", {}, "BUILD OK"), ("gl_probe", {}, "PROBE OK"),+ ("gl_frames", {"times": [0.0, 1.0]}, "FRAMES OK")):+ obs = get_tool(name).call(ctx, args)+ assert not obs.ok and not obs.failed, name+ assert obs.text.splitlines()[0].startswith("FRAME GATE: FAIL — 1 error(s)"), (name, obs.text)+ assert "do not re-run blind" in obs.text.splitlines()[0], name+ assert ok_headline in obs.text and "static image" in obs.text, name+ assert obs.numbers["gate_errors"] == 1, name++def test_load_plan_recognises_graphics_plan(tmp_ws: Workspace) -> None:from codeverse.contracts.plan import GraphicsPlan, PassPlanfrom codeverse.spatial.tool_common import load_plandiff --git a/harness/tests/spatial_tools/test_tools_cli.py b/harness/tests/spatial_tools/test_tools_cli.pynew file mode 100644index 00000000..20b652e6--- /dev/null+++ b/harness/tests/spatial_tools/test_tools_cli.py@@ -0,0 +1,49 @@+"""`3dcv tools <name>`: the three-state panel and the exit code behind it."""++from __future__ import annotations++import json++from typer.testing import CliRunner++from codeverse.cli._common import console, print_observation+from codeverse.spatial.registry import Observation, ToolContext+++def _panel_title(obs: Observation) -> str:+ with console.capture() as cap:+ print_observation(obs, as_json=False)+ return cap.get().splitlines()[0]+++def test_print_observation_shows_three_states() -> None:+ """ok / FAIL / error, the same split the MCP server reports as ``is_error``: a human+ reading `3dcv tools check_connectivity` must be able to tell a gate that answered FAIL+ from a tool that could not run, and the panel title is where they look."""+ assert "ok" in _panel_title(Observation(ok=True, text="fine"))+ assert "FAIL" in _panel_title(Observation(ok=False, text="connectivity: FAIL — 1 error(s)"))+ assert "error" in _panel_title(Observation(ok=False, failed=True, text="measure: no GLB"))+ # --json-out carries both flags, so a script does not have to parse the panel+ with console.capture() as cap:+ print_observation(Observation(ok=False, text="connectivity: FAIL"), as_json=True)+ data = json.loads(cap.get())+ assert data["ok"] is False and data["failed"] is False+++def test_cli_exit_code_follows_the_verdict_not_the_failure(stool_ctx: ToolContext) -> None:+ """`3dcv tools` exits 1 on ``not ok`` — a FAIL verdict included. Deliberate, and it+ DID change one command: `scene_probe` used ``ok`` for "the probe tool ran", so a failing+ scene gate now exits 1 where it exited 0 (docs/COST.md §30). Every other gate tool+ already exited 1 on a FAIL; the exit code speaks to the human or script at the terminal,+ while the MCP boundary — the one that costs money when a verdict is called an error —+ reports ``failed`` alone."""+ from codeverse.cli.main import app++ runner = CliRunner()+ ws = str(stool_ctx.workspace.root)+ good = runner.invoke(app, ["tools", "measure", "--workspace", ws])+ assert good.exit_code == 0, good.output+ verdict = runner.invoke(app, ["tools", "check_connectivity", "--workspace", ws])+ assert verdict.exit_code == 1 and "Leg_3" in verdict.output # the gate ran, and it FAILs+ broken = runner.invoke(app, ["tools", "isolate", "--json", '{"part": "Nope"}', "--workspace", ws])+ assert broken.exit_code == 1 and "unknown part" in broken.output