Skip to content

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.py
index 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`` per
observation image (base64 PNG, long side ≤ 1024 px, at most ``MAX_IMAGES``).
``is_error`` is ``Observation.failed`` (the tool could not run) — never a
negative 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 Any
from PIL import Image
-from codeverse.spatial.observe import fmt_numbers
+from codeverse.spatial.observe import fmt_numbers, truncate
from codeverse.spatial.registry import Observation, ToolContext, list_tools
from codeverse.spatial.tool_common import spec_dict
from codeverse.workspace import Workspace
@@ -32,6 +35,11 @@ from codeverse.workspace import Workspace
MAX_IMAGES = 4
MAX_IMAGE_SIDE = 1024
MAX_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 = 6000
SERVER_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 types
text = obs.text
if 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.py
index 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_individ
numbers["fps"] = rs.fps
if 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.py
index 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):
@classmethod
def 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.py
index 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.summary
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.md
index 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.md
index 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.md
index 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_frames
from codeverse.spatial.registry import tool, get_tool, list_tools, tool_cards, ToolContext, Observation
Observation{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.md
index 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 r
3dcv 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 0
3dcv 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.py
index 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"]) == 0
data = json.loads(capsys.readouterr().out)
diff --git a/harness/tests/spatial_tools/test_observe.py b/harness/tests/spatial_tools/test_observe.py
index 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.py
index 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: pyte
assert 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, PassPlan
from codeverse.spatial.tool_common import load_plan
diff --git a/harness/tests/spatial_tools/test_tools_cli.py b/harness/tests/spatial_tools/test_tools_cli.py
new file mode 100644
index 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