fix(diagnostics): keep GL out of the evidence render thread; name failed renders

The evidence render ran on a daemon thread that imported VTK and, on
non-macOS, executed in-process GL — a native crash there killed the whole
process mid-test-suite (observed on CI), and under load the 15s budget
turned into silently missing evidence.

The screenshot pipeline now splits into prepare (validate + tessellate,
main thread) and execute (render plan: in-process or crash-isolated
worker subprocess). The diagnostic evidence channel prepares on the
calling thread and always executes worker_isolated, so its daemon thread
only ever orchestrates a subprocess.

A render that cannot finish within its budget now reports a named
'render-unavailable' evidence entry instead of vanishing; the budget is
tunable via SCA_DIAGNOSTIC_RENDER_BUDGET (tests: 60s, default: 15s).

Also updates two addon tests to the 2.1.3 runtime-state contract:
remove deletes three recorded locations (payload, skill, runtime dir)
and effective_command takes runtime_dir.
This commit is contained in:
NiJingzhe
2026-09-18 12:10:23 +08:00
parent 1f7d0cb9fa
commit 98bed08a20
8 changed files with 333 additions and 106 deletions
+7
View File
@@ -49,6 +49,13 @@ wheel that ships the Agent Skill source for installation on any machine.
### Fixed
- Diagnostic evidence rendering no longer crashes the process or vanishes
silently: GL work is kept out of the failure path's render thread (the
crash-isolated worker subprocess is used on every platform there), a
render that cannot finish within its budget is reported as a named
`render-unavailable` evidence entry instead of silently missing, and the
budget is tunable via `SCA_DIAGNOSTIC_RENDER_BUDGET` (tests use 60 s; the
agent-facing default stays 15 s).
- Windows build blockers: binary file opens, guarded directory fsync,
and evidence-based stale-lock handling.
- Translator: unified geometry signatures and SolidWorks 2023 support.
+3 -1
View File
@@ -159,7 +159,9 @@ def format_llm_error(operation: str, guidance: ErrorGuidance) -> str:
if guidance.evidence:
lines.append("Evidence:")
for item in guidance.evidence:
rendered = f"- {item.kind} view '{item.view or 'default'}': {item.path}"
rendered = f"- {item.kind} view '{item.view or 'default'}'"
if item.path:
rendered += f": {item.path}"
if item.caption:
rendered += f" ({item.caption})"
lines.append(rendered)
+111 -14
View File
@@ -652,7 +652,7 @@ def _write_window_supersampled(window, output: Path, factor: int) -> None:
downsampled.save(output)
def _render_sdk_screenshot_rpath(
def _prepare_sdk_screenshot(
solids: Sequence[Any], # SDK Solid or raw TopoDS_Shape
output_path: str | Path,
*,
@@ -673,8 +673,17 @@ def _render_sdk_screenshot_rpath(
supersample: int = 2,
highlight_edges: Sequence[Any] = (),
highlight_edge_width: float = 4.5,
) -> Path:
"""Render SDK solids in an isolated VTK worker on macOS.
worker_isolated: bool = False,
) -> tuple[str, Any]:
"""Validate inputs and build the render datasets (no GL work).
This is the half of the SDK screenshot pipeline that imports VTK/OCP
and tessellates — it must run on the calling (main) thread. The
returned plan is executed by :func:`_execute_polydata_render`, which
is safe to run from a worker thread because it only orchestrates GL
work (in-process on non-macOS, or the crash-isolated subprocess when
``worker_isolated`` is set — the diagnostic evidence channel always
sets it).
``views`` switches to the multi-view grid engine: every invocation then
renders one tiled image with a panel per ``(elevation, azimuth, label)``
@@ -854,7 +863,7 @@ def _render_sdk_screenshot_rpath(
edge_groups = [(edge_polydata, highlight_color)]
if show_legend:
legend_pairs = legend_pairs + [("highlighted edges", highlight_color)]
return _render_polydata_views(
return _prepare_polydata_render(
datasets["base"],
output_path,
title="SDK screenshot",
@@ -874,6 +883,7 @@ def _render_sdk_screenshot_rpath(
style=style,
zoom=zoom if len(normalized_views) == 1 else None,
view_up=view_up,
worker_isolated=worker_isolated,
)
def _add_corner_axes(window, source_renderer, rect, *, corner="bottom-left") -> None:
"""Overlay a small orientation triad in a corner of one panel's viewport.
@@ -1558,7 +1568,7 @@ def _render_polydata_views_in_process(
return output
def _render_polydata_views(
def _prepare_polydata_render(
base_polydata,
output_path: str | Path,
*,
@@ -1590,7 +1600,15 @@ def _render_polydata_views(
zoom: float | None = None,
view_up: Sequence[float] | None = None,
datasets: Mapping[str, Any] | None = None,
) -> Path:
worker_isolated: bool = False,
) -> tuple[str, Any]:
"""Validate inputs and build a render plan (no GL work on this thread).
Returns ``(kind, payload)`` for :func:`_execute_polydata_render`:
``("in-process", ...)`` on non-macOS synchronous callers, or
``("worker", ...)`` on macOS (native crash isolation) and whenever
``worker_isolated`` is requested (callers rendering from a thread).
"""
if not views:
raise ValueError("at least one render view is required")
if dpi < 1 or image_size[0] <= 0.0 or image_size[1] <= 0.0:
@@ -1628,12 +1646,10 @@ def _render_polydata_views(
"view_up": None if view_up is None else [float(value) for value in view_up],
"datasets": datasets,
}
if sys.platform != "darwin":
return _render_in_process(
_render_polydata_views_in_process,
base_polydata,
output_path,
**kwargs,
if not worker_isolated and sys.platform != "darwin":
return (
"in-process",
(_render_polydata_views_in_process, base_polydata, output_path, kwargs),
)
datasets: dict[str, Any] = {
"base": base_polydata,
@@ -1676,8 +1692,89 @@ def _render_polydata_views(
if option_name == "surface_groups":
item["opacity"] = group[2]
options[option_name].append(item)
return _run_render_worker(
mode="views", output_path=output_path, datasets=datasets, options=options
return ("worker", {"mode": "views", "output_path": output_path, "datasets": datasets, "options": options})
def _execute_polydata_render(plan: tuple[str, Any]) -> Path:
"""Execute a prepared render plan; thread-safe (no native imports).
``plan`` is what :func:`_prepare_polydata_render` returned: either an
in-process render (non-macOS synchronous callers) or a crash-isolated
worker subprocess invocation (macOS, and any caller that must keep GL
work out of its own process — the diagnostic evidence channel, which
renders from a daemon thread).
"""
kind, payload = plan
if kind == "worker":
return _run_render_worker(**payload)
function, base_polydata, output_path, render_kwargs = payload
return _render_in_process(function, base_polydata, output_path, **render_kwargs)
def _render_polydata_views(
base_polydata,
output_path: str | Path,
*,
title: str,
views: Sequence[tuple[float, float, str]],
image_size: tuple[float, float],
dpi: int,
context_opacity: float = 1.0,
highlight_edge_width: float = 4.5,
highlight_point_size: float = 15.0,
brep_edge_polydata=None,
highlighted_polydata=None,
highlighted_edge_polydata=None,
highlighted_point_polydata=None,
highlighted_groups=None,
highlighted_edge_groups=None,
highlighted_point_groups=None,
legend: Sequence[tuple[str, tuple[float, float, float]]] | None = None,
legend_columns: int = 1,
legend_panel: bool = False,
show_axes: bool = False,
callouts: Sequence[
tuple[str, tuple[float, float, float], tuple[float, float, float]]
| tuple[str, tuple[float, float, float], tuple[float, float, float], str | None]
] | None = None,
edge_width_scale: float = 0.0019,
supersample: int = 1,
style: str = "standard",
zoom: float | None = None,
view_up: Sequence[float] | None = None,
datasets: Mapping[str, Any] | None = None,
) -> Path:
"""Prepare and execute one multi-view render synchronously."""
return _execute_polydata_render(
_prepare_polydata_render(
base_polydata,
output_path,
title=title,
views=views,
image_size=image_size,
dpi=dpi,
context_opacity=context_opacity,
highlight_edge_width=highlight_edge_width,
highlight_point_size=highlight_point_size,
brep_edge_polydata=brep_edge_polydata,
highlighted_polydata=highlighted_polydata,
highlighted_edge_polydata=highlighted_edge_polydata,
highlighted_point_polydata=highlighted_point_polydata,
highlighted_groups=highlighted_groups,
highlighted_edge_groups=highlighted_edge_groups,
highlighted_point_groups=highlighted_point_groups,
legend=legend,
legend_columns=legend_columns,
legend_panel=legend_panel,
show_axes=show_axes,
callouts=callouts,
edge_width_scale=edge_width_scale,
supersample=supersample,
style=style,
zoom=zoom,
view_up=view_up,
datasets=datasets,
)
)
def render_shape_views_rpath(
shape: TopoDS_Shape,
+56 -33
View File
@@ -503,15 +503,15 @@ def render_failure_evidence(
highlight_edges: Sequence[Any] = (),
callouts: bool = True,
) -> Optional[ErrorEvidence]:
"""Render one diagnostic image; never raises, returns None when skipped.
"""Render one diagnostic image; never raises.
Skips when disabled, when this failure signature already rendered once in
the process (agent retry loops must not re-pay the render), or when the
render exceeds the budget — the error goes out immediately in all cases.
``highlight_tags`` drives the designed color channel: tagged faces (or
whole tagged solids) get palette colors, a legend, and callout labels —
a highlight the agent can actually see, not just geometry in the scene.
Skips (returns None) when disabled or when this failure signature
already rendered once in the process — agent retry loops must not
re-pay the render. When a render is attempted but produces no image
(worker failure, or it exceeds the ``SCA_DIAGNOSTIC_RENDER_BUDGET``
budget, 15 seconds by default), the evidence channel carries a
``render-unavailable`` entry naming the reason: the error goes out
immediately either way, and a vanished render is never silent.
"""
if not diagnostics_enabled():
@@ -525,42 +525,65 @@ def render_failure_evidence(
root.mkdir(parents=True, exist_ok=True)
stamp = datetime.now().strftime("%Y%m%d-%H%M%S-%f")
path = root / f"{operation}-{stamp}.png"
from .features import render_screenshot_rpath
from .features import _execute_screenshot_render, _prepare_screenshot_render
# Prepare (validate + tessellate) on the calling thread: this is
# where the heavy native imports happen, and a native crash must
# never originate inside a daemon thread where it takes the whole
# process down. The thread below only orchestrates the
# crash-isolated worker subprocess.
prepared = _prepare_screenshot_render(
shapes,
str(path),
views=_DIAGNOSTIC_VIEWS,
supersample=1, # highlight lines are fixed-width; SSAA is not worth the budget
edge_width_scale=0.0035, # heavier model ink so panels read at grid size
highlight_edge_width=8.0, # highlights outweigh the ink, always
highlight_tags=tuple(highlight_tags),
tag_labels=dict(tag_labels or {}),
highlight_edges=tuple(highlight_edges),
show_legend=bool(highlight_tags or highlight_edges),
show_callouts=bool(highlight_tags) and callouts,
worker_isolated=True, # a daemon thread must never run in-process GL
)
budget = float(os.environ.get("SCA_DIAGNOSTIC_RENDER_BUDGET", _RENDER_BUDGET_SECONDS))
result: dict = {}
def _render() -> None:
try:
render_screenshot_rpath(
shapes,
str(path),
views=_DIAGNOSTIC_VIEWS,
supersample=1, # highlight lines are fixed-width; SSAA is not worth the budget
edge_width_scale=0.0035, # heavier model ink so panels read at grid size
highlight_edge_width=8.0, # highlights outweigh the ink, always
highlight_tags=tuple(highlight_tags),
tag_labels=dict(tag_labels or {}),
highlight_edges=tuple(highlight_edges),
show_legend=bool(highlight_tags or highlight_edges),
show_callouts=bool(highlight_tags) and callouts,
)
result["path"] = str(path)
except Exception:
pass
result["path"] = _execute_screenshot_render(prepared)
except Exception as exc:
result["error"] = f"{type(exc).__name__}: {exc}"
worker = threading.Thread(target=_render, daemon=True)
worker.start()
worker.join(_RENDER_BUDGET_SECONDS)
if "path" not in result:
return None
worker.join(budget)
if "path" in result:
return ErrorEvidence(
kind="render",
path=result["path"],
view=view,
caption=caption,
)
if "error" in result:
reason = result["error"]
elif worker.is_alive():
reason = f"exceeded the {budget:g}s diagnostic render budget"
else:
reason = "the render worker produced no image"
return ErrorEvidence(
kind="render",
path=result["path"],
kind="render-unavailable",
path="",
view=view,
caption=caption,
caption=f"diagnostic render unavailable: {reason}",
)
except Exception as exc:
return ErrorEvidence(
kind="render-unavailable",
path="",
view=view,
caption=f"diagnostic render unavailable: {type(exc).__name__}: {exc}",
)
except Exception:
return None
@dataclass(frozen=True)
+134 -50
View File
@@ -371,7 +371,7 @@ class _RenderTagMismatch(ValueError):
"""
def render_screenshot_rpath(
def _prepare_screenshot_render(
shapes: Union[Solid, Sequence[Solid], Any],
output_path: str,
highlight_tags: Optional[Sequence[str]] = None,
@@ -391,36 +391,15 @@ def render_screenshot_rpath(
supersample: int = 2,
highlight_edges: Optional[Sequence[Any]] = None,
highlight_edge_width: float = 4.5,
) -> str:
"""Render solids or raw TopoDS shapes through the one OCCT/VTK pipeline.
worker_isolated: bool = False,
) -> Any:
"""Normalize inputs and build render datasets for one screenshot.
``shapes`` accepts SDK ``Solid`` objects (with full tag highlight,
callout and legend support) or raw ``TopoDS_Shape`` entries from the
STEP inspection family (same engine, same edge ink and supersampling,
no tag features).
``highlight_edges`` draws the given edges (SDK ``Edge`` objects or raw
``TopoDS_Edge``) as crisp orange highlight lines exactly on the edge —
the failure-marking channel used by the blend diagnostics.
There is exactly one output form: a multi-view grid of one to four
panels, each carrying annotations. ``view="auto"`` (default) uses the
standard four-view set; an explicit preset name or ``(elevation,
azimuth)`` pair renders a single full-frame panel; ``views`` accepts
up to four explicit ``(elevation, azimuth, label)`` triples.
``zoom`` applies to single-panel renders only.
``supersample (default 2) renders at an integer multiple and
downsamples with LANCZOS for deterministic crisp edges; 1 renders 1:1.
``style="studio"`` turns the single-view path into a product shot
(gradient backdrop, three-point lighting, bold tubed BRep edges);
``linear_deflection``/``angular_deflection`` tighten the tessellation
for high-resolution exports. ``edge_width_scale`` tunes the studio edge
tube radius as a fraction of model span (default 0.0026; use ~0.001 for
exploded stacks so the ink does not swamp small parts).
Imports VTK/OCP and tessellates — main thread only. Pair with
:func:`_execute_screenshot_render`, which is thread-safe.
"""
try:
from ..inspect.brep.render import _render_sdk_screenshot_rpath
from ..inspect.brep.render import _execute_polydata_render, _prepare_sdk_screenshot
shape_list = _normalize_shape_input(shapes)
solids = [
@@ -474,28 +453,27 @@ def render_screenshot_rpath(
+ f" — available tags on these shapes: {shown}{more}; "
"check tag names and the build stage that produced them"
)
return str(
_render_sdk_screenshot_rpath(
solids,
output_path,
highlight_tags=tuple(highlight_tags or ()),
tag_labels=tag_labels,
image_size=image_size,
view=view,
show_axes=show_axes,
show_legend=show_legend,
zoom=zoom,
show_callouts=show_callouts,
linear_deflection=linear_deflection,
angular_deflection=angular_deflection,
views=resolved_views,
style=style,
edge_width_scale=edge_width_scale,
view_up=tuple(float(value) for value in view_up) if view_up is not None else None,
supersample=supersample,
highlight_edges=tuple(highlight_edges) if highlight_edges else (),
highlight_edge_width=highlight_edge_width,
)
return _prepare_sdk_screenshot(
solids,
output_path,
highlight_tags=tuple(highlight_tags or ()),
tag_labels=tag_labels,
image_size=image_size,
view=view,
show_axes=show_axes,
show_legend=show_legend,
zoom=zoom,
show_callouts=show_callouts,
linear_deflection=linear_deflection,
angular_deflection=angular_deflection,
views=resolved_views,
style=style,
edge_width_scale=edge_width_scale,
view_up=tuple(float(value) for value in view_up) if view_up is not None else None,
supersample=supersample,
highlight_edges=tuple(highlight_edges) if highlight_edges else (),
highlight_edge_width=highlight_edge_width,
worker_isolated=worker_isolated,
)
except Exception as e:
_wrap_public_api_error(
@@ -519,6 +497,112 @@ def render_screenshot_rpath(
error=e,
)
def _execute_screenshot_render(prepared: Any) -> str:
"""Run the prepared render (GL work); thread-safe via the render plan.
On macOS the GL work runs in the crash-isolated worker subprocess;
elsewhere it runs in-process and therefore belongs on the main
thread — the diagnostic evidence channel always requests
``worker_isolated`` so its daemon thread only ever touches a
subprocess.
"""
from ..inspect.brep.render import _execute_polydata_render
return str(_execute_polydata_render(prepared))
def render_screenshot_rpath(
shapes: Union[Solid, Sequence[Solid], Any],
output_path: str,
highlight_tags: Optional[Sequence[str]] = None,
tag_labels: Optional[Dict[str, str]] = None,
image_size: Tuple[int, int] = (1400, 900),
view: Union[Tuple[float, float], str] = "auto",
views: Optional[Sequence[Tuple[float, float, str]]] = None,
show_axes: bool = True,
show_legend: bool = True,
zoom: float = 4.0,
show_callouts: bool = True,
linear_deflection: Optional[float] = None,
angular_deflection: Optional[float] = None,
style: str = "studio",
edge_width_scale: Optional[float] = None,
view_up: Optional[Sequence[float]] = None,
supersample: int = 2,
highlight_edges: Optional[Sequence[Any]] = None,
highlight_edge_width: float = 4.5,
) -> str:
"""Render solids or raw TopoDS shapes through the one OCCT/VTK pipeline.
``shapes`` accepts SDK ``Solid`` objects (with full tag highlight,
callout and legend support) or raw ``TopoDS_Shape`` entries from the
STEP inspection family (same engine, same edge ink and supersampling,
no tag features).
``highlight_edges`` draws the given edges (SDK ``Edge`` objects or raw
``TopoDS_Edge``) as crisp orange highlight lines exactly on the edge —
the failure-marking channel used by the blend diagnostics.
There is exactly one output form: a multi-view grid of one to four
panels, each carrying annotations. ``view="auto"`` (default) uses the
standard four-view set; an explicit preset name or ``(elevation,
azimuth)`` pair renders a single full-frame panel; ``views`` accepts
up to four explicit ``(elevation, azimuth, label)`` triples.
``zoom`` applies to single-panel renders only.
``supersample (default 2) renders at an integer multiple and
downsamples with LANCZOS for deterministic crisp edges; 1 renders 1:1.
``style="studio"`` turns the single-view path into a product shot
(gradient backdrop, three-point lighting, bold tubed BRep edges);
``linear_deflection``/``angular_deflection`` tighten the tessellation
for high-resolution exports. ``edge_width_scale`` tunes the studio edge
tube radius as a fraction of model span (default 0.0026; use ~0.001 for
exploded stacks so the ink does not swamp small parts).
The prepare half (validation + tessellation) runs on the calling
thread; the GL work runs in a crash-isolated worker subprocess, so a
native VTK crash can never take the caller down.
"""
prepared = _prepare_screenshot_render(
shapes,
output_path,
highlight_tags=highlight_tags,
tag_labels=tag_labels,
image_size=image_size,
view=view,
views=views,
show_axes=show_axes,
show_legend=show_legend,
zoom=zoom,
show_callouts=show_callouts,
linear_deflection=linear_deflection,
angular_deflection=angular_deflection,
style=style,
edge_width_scale=edge_width_scale,
view_up=view_up,
supersample=supersample,
highlight_edges=highlight_edges,
highlight_edge_width=highlight_edge_width,
)
try:
return _execute_screenshot_render(prepared)
except Exception as e:
_wrap_public_api_error(
operation="render_screenshot_rpath",
what_happened="Failed to render the screenshot.",
possible_causes=[
"The rendering view or zoom configuration is invalid.",
"The output path is invalid or not writable.",
],
how_to_fix=[
"Use a supported view preset or a valid (elev, azim) tuple.",
"Check that the output path is writable.",
],
error=e,
)
def fillet_rsolid(
solid: Solid,
edges: Union[Sequence[Edge], ShapeSelector],
+4 -1
View File
@@ -6,5 +6,8 @@ import os
# Failure-path evidence rendering stays off for the suite at large: it is
# slow (VTK worker per render) and exercises nothing those tests assert.
# Dedicated evidence tests opt back in via monkeypatch.delenv.
# Dedicated evidence tests opt back in via monkeypatch.delenv. Their
# per-render budget scales with the slowest runner (cold CI workers), not
# with the agent-facing default.
os.environ.setdefault("SCA_NO_DIAGNOSTIC_RENDER", "1")
os.environ.setdefault("SCA_DIAGNOSTIC_RENDER_BUDGET", "60")
+5 -2
View File
@@ -295,7 +295,7 @@ def test_update_unknown_name_lists_installed(tmp_path):
# ------------------------------------------------------------------ remove
def test_remove_deletes_both_locations(tmp_path):
def test_remove_deletes_all_recorded_locations(tmp_path):
_init(tmp_path)
source = _make_addon_repo(tmp_path)
run(["addon", "add", str(source)])
@@ -304,8 +304,11 @@ def test_remove_deletes_both_locations(tmp_path):
home = tmp_path / ".sca" / "addons"
assert not (home / "demo-addon").exists()
assert not (tmp_path / ".agents" / "skills" / "sca-demo-addon").exists()
# Runtime state (the provisioned venv) is removed with the addon,
# never left orphaned.
assert not (tmp_path / ".sca" / "runtimes" / "demo-addon").exists()
assert _registry(home)["addons"] == {}
assert len(report["removed"]) == 2
assert len(report["removed"]) == 3
with pytest.raises(AddonError) as err:
run(["addon", "remove", "demo-addon"])
+13 -5
View File
@@ -399,10 +399,18 @@ def test_command_prefix_rejects_unknown_placeholder(tmp_path):
assert "{addon_dir}" in str(err.value)
def test_effective_command_joins_prefix_and_substitutes_addon_dir():
def test_effective_command_joins_prefix_and_substitutes_both_dirs():
from simplecadapi.addon.install import effective_command
prefix = 'PATH="{addon_dir}/.venv/bin:$PATH"'
effective = effective_command(prefix, Path("/addons/demo"), "python -V")
assert effective == 'PATH="/addons/demo/.venv/bin:$PATH" python -V'
assert effective_command("", Path("/addons/demo"), "python -V") == "python -V"
prefix = 'PATH="{addon_dir}/.venv/bin:$PATH" SCA_RUNTIME_DIR="{runtime_dir}"'
effective = effective_command(
prefix, Path("/addons/demo"), Path("/sca/runtimes/demo"), "python -V"
)
assert effective == (
'PATH="/addons/demo/.venv/bin:$PATH" '
'SCA_RUNTIME_DIR="/sca/runtimes/demo" python -V'
)
assert (
effective_command("", Path("/addons/demo"), Path("/sca/runtimes/demo"), "python -V")
== "python -V"
)