Render sketches despite downstream KCL failures

[ksbharaj]

Summary

• Try executing through a safely identified top-level solver sketch before full execution, avoiding later consumers. Eligible first solid-helper instances use the native targeted execution path; unsupported or failed shortcuts fall back to full execution.

• Apply one shared, configurable SKETCH_VISUALIZATION_TIMEOUT budget (120 seconds by default) across the entire visualization, including retries and fallbacks. Expiry raises ZooMCPTimeoutError without starting another attempt. The native binding aborts its async execution task on cancellation; no TTC or native timer is added.

• Retry visualize_sketch with a parseable KCL prefix ending after the requested top-level sketch whenever full-project execution ultimately fails.

• Preserve complete pipeline geometry, relative imports, relevant project files, and project.toml in an isolated temporary project without mutating the caller's files.

• Recognize valid KCL formatting and identifiers without matching declarations inside comments or multiline strings.

• Preserve the transient WebSocket-auth retry from Retry transient websocket auth failures #246 before falling back to isolated sketch execution.

• Expose an optional instance_index for duplicate sketch names, using the zero-based creation order in a fresh same-entrypoint constraint report. Unique-name calls keep their existing behavior.

Why

The merged MCP implementation executes the full file before rendering, including downstream 3D work. A guarded sketch-first prefix avoids later work when selection is unambiguous. The existing recovery path also keeps a valid sketch inspectable when a later region, extrude, loft, boolean, or consumed-region operation fails. This is not caching or general dependency-aware slicing. A separate conservative native shortcut can skip unrelated work for the first instance of a directly called solid helper with constant inputs.

Verification

• 33 focused sketch-visualization tests pass with the local native build, including real PNG rendering, inline and project-path KCL, an imported sketch dependency, project.toml, complete pipelines, retryable engine failures, and downstream execution failures.
• Direct checks returned PNGs despite downstream open-extrude, open-loft, invalid-region-segment, and invalid-region-query-point errors.
• Full/prefix PNG and constraint-report equivalence tested on XY, an offset plane, and the face of a preceding solid; original imports and duplicate-instance tests still pass.
• Ruff formatting/linting and ty type checking pass.

Deliberate limits

• Errors inside the selected sketch or its required dependencies still block rendering. The eligible helper shortcut can omit unrelated operations before or after it.
• Imported modules are copied whole, so errors inside an imported module are not recursively isolated.
• Prefix sketch-first remains conservative for imports, aliases, later whole-sketch operations, selected-sketch pipelines and later module settings. Explicit instance_index=0 can use the native shortcut only for an eligible solid helper on XY/XZ/YZ, called directly with constants or arithmetic on earlier literal constants. Other indices and unsupported helper shapes keep full execution.
• The prefix path keeps earlier operations, including geometry needed for face placement. The eligible helper path skips unrelated operations; face-dependent sketches are not eligible.
• Execution still requires the engine; retries remain bounded, and an unavailable engine can delay or prevent rendering.

Draft renderer dependency

Explicit instance selection requires KittyCAD/modeling-app#13734. pyproject.toml and uv.lock temporarily pin zoo-kcl to f5bb4d5bc4d37b6c4651ad2802ddd2caf4b41238; replace the Git pin with a published release before merging/releasing. The original Two-Robot-Tool Mount checkpoint now renders both slotProfile instances without KCL edits. Indices are valid for the current entrypoint/source, not persistent identities across edits.

Direct sketch-first benchmark (2026-09-10)

Reconstructed the exact successful file revisions for actual Steel Switch Box visualization calls in trace 01a087a8-bb4a-7142-b1c0-880d5893e79c, verified SHA-256 against recorded file_revisions, and benchmarked directly against full execution with the same pinned native build. No Zookeeper eval was launched.

Selected sketch	Paired repeats	Full + PNG (mean ± sample SD)	Sketch-first + PNG	Result
tabSketch	3	8.779 ± 0.740 s	5.955 ± 0.120 s	32.2% faster
rimNotchSketch	2	103.527 ± 3.259 s	104.128 ± 6.355 s	No demonstrated gain
crimpSketch	1	101.227 s	104.607 s	No demonstrated gain

Every comparison produced byte-identical PNGs and identical selected-sketch constraint reports, with no benchmark failures/retries. PNG rendering itself took about 0.28–0.32 s. The late-sketch results confirm that prefix execution does not avoid expensive preceding booleans. A rim pilot overlapped integration tests and is excluded from the table; including it does not change the verdict. The crimp baseline reuses the matching full rim execution outcome, with its PNG timed separately. These are microbenchmarks, not evidence of an overall Zookeeper speedup.

Source revisions: tab c09058053fc49ca343b4084ef9208968df37fa0b95559670cfda905329fdfb69; rim/crimp 321511cfabbda23f350f7fd958d36d6d4d099239f8d3e58948e9988983ac5a9f.

Direct Flanges instance benchmark (2026-09-11)

Replayed the exact SHA-256-verified files from two actual padSketch, instance_index=0 calls in the original trace. No KCL was regenerated or edited for the benchmark.

Checkpoint	Historical tool call	New native shortcut, mean ± sample SD	Repeats	PNG vs original
First	618.647 s	1.824 ± 0.041 s	3	Byte-identical
Second	518.791 s	1.674 ± 0.136 s	3	Byte-identical

Historical timings are context, not a controlled speedup ratio. On the same current native build and engine environment, full execution of the second checkpoint timed out at 240.100 s; its shortcut completed in about 1.7 s. An earlier full-execution pilot for the first checkpoint also reached its 240-second cap, before the rebase. Neither capped run produced a PNG. These microbenchmarks do not establish the change in total Zookeeper runtime or overall CAD quality.

The second real checkpoint exposed a narrow eligibility gap: depth = webThickness + ribHeight. The native guard now accepts arithmetic on literals/earlier literal constants, retaining normal KCL evaluation and rejecting function calls or unresolved dependencies. Three-plane real-engine regression tests preserve PNG bytes, nonempty constraint reports and sketch placement. The exact Flanges comparison verifies PNG identity; its report/placement equivalence was not independently measured from a completed new full execution.

Native build: f5bb4d5bc4d37b6c4651ad2802ddd2caf4b41238 (KCL 0.3.184, local debug build). Source SHA-256: first fdbd0ef15266ec69393bd1f329e7621d25801ab33e032e4d6fa1471c9ecf46c0; second 0dab18991cb5b92e77dbb68f02956ff0f28262a0af52aaf579e53fc8c303034a.