Files

T

earthtojakeandClaude Opus 5.5 523ae21341 Release 0.7.19: fix what day one of PostHog telemetry showed (Windows mesh export, cad_file and cad_screenshot failures, crash noise, failure reasons) (#586 )

**This PR is the 0.7.19 release** (`scripts/release/bump-version.sh
patch`): merging it runs Publish Release. Its receiver changes under
`apps/api` deploy on the same merge through Deploy API, minutes before
PyPI has 0.7.19, so schema 4 is read before any client sends it.

Fixes for what PostHog's first day of telemetry showed (2026-10-08
00:14Z to about 21:40Z: about 209 installs and 59 crash reports). It
covers three bugs people are hitting, crash reports that were not
cadgen's bugs, and gaps in what the receiver lets us see. There is one
commit per fix.

## Bugs

**1. Builds that export a mesh crashed on Windows** (7 installs, all
Windows, about 26 crashes). `mesh_export.py` ran the Node exporter with
`text=True` and no encoding, so Windows read its UTF-8 output in the
local code page. The exporter's JSON report names every output path, so
any output folder whose name the code page cannot read (for example
`Рабочий стол` under cp1252, or most Chinese text under cp936) made
CPython's Windows output reader die quietly. `proc.stdout` came back
`None`, and `.splitlines()` raised an `AttributeError`. The exporter now
reads `utf-8` with `errors="replace"`, which keeps the JSON line intact.
The same fix goes into `run_node_builder`, whose input was also silently
empty under cp1252. ffmpeg, `gz sdf` and `doctor` now read `utf-8` with
`errors="backslashreplace"`, and doctor's child process is set to
`PYTHONIOENCODING=utf-8`. The tests force subprocess's default encoding
to cp1252, and both fail without the fix.

**2. `cad_file` failed on 48 of 49 calls on Windows** (5 of 6 installs).
Codex for Windows names a file opened from its file tree as
`openai/resource.path = "/C:/Users/…"`, read from the desktop bundle.
Python 3.13's `ntpath.isabs("/C:/…")` is False, so every call answered
"not an absolute path". The `file.resourceUri` alongside it is a
`codex-resource://` handle, so the fallback never helped. A new
`local_path` drops the slash before a drive on Windows, both for file
URIs and for plain paths, for `cad_file`, `cad_open` and `cad_show`.
This most likely also explains Antigravity's `cad_show` failures on
Windows (7 of 12). The Windows CI job now passes the path the way Codex
spells it.

**3. `cad_screenshot` failed on 30% of calls** (11 of 19 installs). The
most likely cause is an agent capturing straight after build, show or
open, while the view is still loading or has not synced yet. The view
refused with "Wait for the displayed model revision to finish loading",
"That viewer is not open" or "No CAD viewer with a model is open", or a
large model ran past the fixed 10 s wait.
- The page now waits until the view shows the requested model, loaded
and drawn (`CAPTURE_SETTLE_MS`, 20 s).
- The server waits for a view it just opened to sync (`OPENING_SECONDS`,
15 s) within one budget for the whole capture (`CAPTURE_SECONDS`, 40 s).
- The capture's reply still goes on its own call (`void answer(event)`),
so no view call is held open.

## Crash reports that were not cadgen's bugs
- **Windows viewer disconnects.** `ConnectionAbortedError` (WinError
10053) made up most of the crash volume: 23 installs. The viewer caught
only `BrokenPipeError` and `ConnectionResetError`, and the header write
had no guard. Every write to the socket now treats any `ConnectionError`
as the page having left.
- **A model's own mistakes.** A build123d name that does not exist,
raised through the `cadgen.build123d` re-export, and a non-string passed
to `srgb()`. Both now raise deliberately, so the existing rule counts
them as the person's error, and `srgb` raises a `TypeError` naming what
it was given.
- **Stopped workers.** A worker stopped by SIGTERM, SIGINT or SIGHUP (a
person quitting it, a logout) now counts as cancelled, not crashed.
SIGSEGV, SIGABRT and SIGKILL are still reported.

## Telemetry: what we can now see
- **Why a tool call failed.** There is a new `tool_failure {tool,
reason, count}` event in batch schema 4, which PostHog receives as
`tool_failed`. The reason is one word from a fixed list (`no_path`,
`relative_path`, `no_file`, `not_cad`, `no_view`, `wrong_view`,
`bad_request`, `timeout`, `view_error`, `too_large`, `no_viewer`, `bug`,
`other`), chosen where the call fails and never taken from a message. A
test checks that every `ToolFailed` and `NoAnswer` names one.
- **Rollout: the receiver goes first.** The API is its own Vercel
project now (#587) and deploys on merge to `main`, so merging this PR
puts the schema 4 receiver live before any release sends schema 4. A
refused batch is dropped, as before; there is no fallback in the client.
- **Refused batches are logged.** Each 400, 403 or 415 is one
`console.warn` line naming the rule that failed and the cadgen version.
Values, install ids and service messages are never logged. Vercel's
per-status counts need Observability Plus, so this is the only way to
see a refusal. The privacy policy says so.
- **Errors are logged by name**, for example `TimeoutError` instead of
`23`. A `/v1/forget` timed out at 17:02Z, and the client retries it.
- **`$session_id`** is now set, so error tracking can count sessions.
Our ids are UUIDv4, so PostHog's sessions table leaves them out; error
tracking should still read them, which needs checking after deploy.

Privacy policy, README and `apps/api/README.md` are updated where what
is sent or logged changed.

## Not in this PR
- **Deduplicating a resent batch.** The sender rebuilds a failed window
instead of resending it, and a batch has no id, so there is nothing
stable to dedupe on yet. It needs a per-batch id from the sender.
- **Dashboard totals.** PostHog's error-tracking "occurrences" counts
events, not each event's `count`; for the mesh-export crash that is 5
against 22. That is fixed on the dashboard side (t2c-analytics).
- **5 of 15 DXF builds failed.** DXF builds don't go through Node, so
the encoding fix doesn't cover them and they still need a look.

## Needs a real host
- Windows Codex: open a `.step` from the file tree; capture from a tab
hidden behind another tab.
- Claude Desktop: capture right after `cad_show` on a large STEP, or
while the card waits on Allow.
- Antigravity on Windows: confirm the path spelling it sends.

## Tests
Full suites on this branch, in a provisioned worktree (`.venv` from
`requirements-dev.txt`, `npm ci`, `bundle.sh --check`,
`CADGEN_DAEMON=0`): all pass.
- `scripts/test/test-python.sh --keep-going`: 2,774 tests in 8 groups,
OK.
- `scripts/test/test-js.sh`: every group passes (core, ui, web, mcp).
- `scripts/test/test-docs.sh`: receiver tests 30/30 and the rest 16/16.
- `scripts/test/test-global.sh`: 210 tests, OK (1 skipped).

Each new regression test was run against the old code, and each fails
there.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-09 01:35:24 +00:00

9.1 KiB

Raw Permalink Blame History

name, description, license

name	description	license
urdf	URDF robot description authoring and validation. Use when creating, editing, inspecting, validating, or debugging `.urdf` files, robot links, joints, limits, inertials, visual/collision geometry, mesh references, frame conventions, or robot-description artifacts. Use the SRDF skill for MoveIt2 semantic groups and IK/path-planning semantics; use the CAD skill for STEP/STL/3MF/DXF/GLB outputs. Open and visually review existing URDF files in CAD Viewer.	MIT

URDF

Provenance: maintained in earthtojake/text-to-cad. Use the installed local skill files as the runtime source of truth; the repository link is only for provenance and release review.

Use this skill for URDF robot-description outputs. Treat URDF work as constrained kinematic modeling, not just XML writing. The main correctness risks are frame placement, joint-axis semantics, unit consistency, mesh scale, and inertial data.

Setup

Run cadgen through uv, so this skill's commands share one installation, and its warm build daemon, with the CAD app's server:

cadgen below means uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.19 cadgen
python below means uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.19 python

The first run downloads that installation and the first snapshot its headless browser; later runs reuse both.

Core Rules

The .urdf file is the source of truth. Author and edit URDF XML directly; do not build a Python generation pipeline for it. There is no gen_urdf() contract.
Before writing or changing URDF XML, establish the robot's frame, joint, geometry, unit, and assumption ledger and embed it as a comment block at the top of the .urdf file. See references/design-ledger.md.
Use URDF frame semantics exactly. Joint origins, link frames, joint axes, and visual/collision/inertial origins use different reference frames. See references/frame-semantics.md.
Do not infer spatial transforms, mesh units, handedness, axes, or joint signs from vague prose. Use CAD transforms, dimensioned drawings, measured values, existing source data, or explicit documented assumptions.
Never freehand numeric values that are the result of computation — inertia tensors, centers of mass, unit conversions across many links, mirrored transforms. Compute them: closed-form formulas for primitives, or a throwaway helper script for mesh-derived values. See references/inertials.md.
For physical links, model inertial, visual, and collision separately when the target consumer needs them. Frame-only links may intentionally omit mass and geometry.
Validate every created or modified .urdf with cadgen urdf validate before reporting completion. See references/validation.md.
Helper scripts are allowed and encouraged for computation, but they are scaffolding, not the artifact's source of truth. For complex or genuinely parametric models it is reasonable to keep a model-local helper script on disk next to related source code (for example STEP generator sources) and note it in the ledger; this is optional, and the checked-in .urdf remains canonical.

Show the model

Show the user each file you create or change, and any they ask to see. Snapshots and validation don't replace this.

If your tools include cad_show (your host may prefix it), use it with the file's absolute path, and follow its description for when to call it again. cad_view reads what the user selected; cad_screenshot shows you what they see. Neither is a review of your own work.
Otherwise run the CAD Viewer, from any folder:
```
cadgen viewer --host 127.0.0.1 --json --detach
```
--detach returns once the viewer answers requests and leaves it running in the background: always pass it, since a foreground viewer never exits (and piping its output through tail can hide the URL for good). It starts this machine's one viewer, or reuses it. Read url from its one JSON line (never guess the port), and for each file return url?file=<its URL-encoded absolute path>. If it fails to launch, say so.

Review mesh scale and placement, then sweep every movable joint against the design ledger. A link alone does not complete the viewer sweep; report any checks you could not perform.

Workflow

Identify the target .urdf file and its consumers: RViz, robot_state_publisher, Gazebo/Ignition, MoveIt, a real robot driver, or another simulator.
Read or create the design ledger before editing frames, origins, axes, mesh scale, limits, or inertials. Keep the ledger as a comment block in the .urdf itself.
Prepare mesh assets first when links reference meshes: one mesh per link, exported in that link's frame by the owning CAD/mesh workflow. See references/meshes.md.
Author or edit the URDF XML directly, following references/authoring-contract.md for structure, ordering, and naming.
Compute — never guess — inertials and other derived numbers. See references/inertials.md.
Validate with cadgen urdf validate; fix findings and re-validate until clean.
Run the verification recipe in references/validation.md: external tools when available (check_urdf), then a viewer review sweeping every joint.
Report remaining assumptions, unchecked spatial data, and validation gaps.

Commands

Run cadgen as Setup defines it. cadgen doctor <skill-dir> reports the installation in use and checks that it is the one this skill pins — docs drift silently on another. Validation itself needs nothing beyond the Python standard library; only snapshots need the browser. Use cadgen <verb> --help for the complete current interface.

The validator shape is:

cadgen urdf validate path/to/robot.urdf
cadgen urdf validate path/to/robot.urdf --strict
cadgen urdf validate path/to/robot.urdf --json
cadgen urdf validate path/to/robot.urdf --packages robot_description=/path/to/pkg
cadgen urdf snapshot path/to/robot.urdf review.png

The validator collects all findings in one pass (severity, code, XML path) across XML structure, tree topology, joint semantics (limits, mimic, dynamics), geometry, mesh references, materials, inertial physics, and misspelled elements, and prints a summary. One run validates ONE file: --strict treats warnings as failures; --json prints one line of {"ok", "path", "issues": [{"severity", "code", "message", "element", "hint"}], "summary"}, where element is the XML path; --packages NAME=PATH resolves package:// mesh URIs and repeats for several roots. It exits nonzero if the target fails. Relative targets resolve from the current working directory; run from the workspace that owns the files.

Validation is a guardrail, not spatial proof: a URDF can pass every structural check while placing a joint in the wrong spot. The ledger and viewer sweep exist for that reason.

Snapshot Tool

cadgen urdf snapshot renders the robot to a PNG still, using the same shared CLI and headless browser runtime every rendering skill uses — so a snapshot matches what the CAD Viewer shows.

cadgen urdf snapshot path/to/robot.urdf review.png

It accepts .urdf only. Pose the robot with --joint-values — {joint: degrees} JSON, joints you do not name staying at their defaults, where the CAD Viewer opens the robot (the "jointValues" job field is the same thing in a packet). The snapshot draws the robot with the viewer's own scene, so it shows what the viewer shows, and a link mesh that cannot be loaded fails it rather than leaving the link out. Robots are authored in metres and are framed on the robot scene scale automatically.

A normal snapshot uses the Solid preset and Light appearance; omitted groups inherit preset defaults. Pass --display render for the shared photographic scene. Inline display JSON and JSON files use grouped settings such as lighting, background, and floor; appearance is light (default) or dark. Projection and focal length belong in display.camera. Top-level --camera and --joint-values remain active in every display mode. The display modes are solid and render: edges, clip, exploded, the xray, hidden-line and wireframe modes and the hidden/off surface styles describe a STEP model's CAD edges, parts and solids, and are refused by name here.

Link meshes are resolved relative to the description, so they must be present: an unhydrated Git LFS pointer fails as "No link mesh loaded for robot". Run git lfs checkout <mesh dir> first.

The grammar is cadgen urdf snapshot TARGET [OUT] [flags], the same one every format door uses. Use cadgen urdf snapshot --help for the complete current interface — the flags a robot cannot act on are absent from it, not refused by it.

References

Authoring contract (structure, ordering, golden skeleton): references/authoring-contract.md
Design ledger: references/design-ledger.md
Frame semantics: references/frame-semantics.md
Mesh preparation and references: references/meshes.md
Inertials (formulas, scripts, sanity gates): references/inertials.md
URDF edit workflow: references/urdf-workflow.md
Validation and verification recipe: references/validation.md

9.1 KiB Raw Permalink Blame History