@coloopx/colocad 0.0.0-stage → 0.1.0-alpha.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (194) hide show
  1. package/LICENSE +21 -0
  2. package/NOTICE.md +5 -0
  3. package/README.md +131 -2
  4. package/README.zh-CN.md +100 -0
  5. package/bin/colocad.mjs +32 -0
  6. package/examples/manifold.json +11 -0
  7. package/examples/sensor-rail.json +9 -0
  8. package/kernel/LICENSE +21 -0
  9. package/kernel/dist/artifacts.d.ts +3 -0
  10. package/kernel/dist/artifacts.js +19 -0
  11. package/kernel/dist/assets.d.ts +3 -0
  12. package/kernel/dist/assets.js +11 -0
  13. package/kernel/dist/binary.d.ts +2 -0
  14. package/kernel/dist/binary.js +14 -0
  15. package/kernel/dist/client.d.ts +22 -0
  16. package/kernel/dist/client.js +99 -0
  17. package/kernel/dist/files.d.ts +19 -0
  18. package/kernel/dist/files.js +103 -0
  19. package/kernel/dist/generated.d.ts +707 -0
  20. package/kernel/dist/generated.js +1 -0
  21. package/kernel/dist/helpers.d.ts +9 -0
  22. package/kernel/dist/helpers.js +23 -0
  23. package/kernel/dist/index.d.ts +8 -0
  24. package/kernel/dist/index.js +6 -0
  25. package/kernel/dist/preview-cache.d.ts +19 -0
  26. package/kernel/dist/preview-cache.js +29 -0
  27. package/kernel/dist/process.d.ts +12 -0
  28. package/kernel/dist/process.js +41 -0
  29. package/kernel/dist/tools.d.ts +67 -0
  30. package/kernel/dist/tools.js +20 -0
  31. package/kernel/dist/types.d.ts +26 -0
  32. package/kernel/dist/types.js +1 -0
  33. package/kernel/licenses/adler2-2.0.1-LICENSE-0BSD +12 -0
  34. package/kernel/licenses/adler2-2.0.1-LICENSE-APACHE +201 -0
  35. package/kernel/licenses/adler2-2.0.1-LICENSE-MIT +23 -0
  36. package/kernel/licenses/allocator-api2-0.2.21-LICENSE-APACHE +176 -0
  37. package/kernel/licenses/allocator-api2-0.2.21-LICENSE-MIT +23 -0
  38. package/kernel/licenses/autocfg-1.5.1-LICENSE-APACHE +201 -0
  39. package/kernel/licenses/autocfg-1.5.1-LICENSE-MIT +25 -0
  40. package/kernel/licenses/bitflags-1.3.2-LICENSE-APACHE +201 -0
  41. package/kernel/licenses/bitflags-1.3.2-LICENSE-MIT +25 -0
  42. package/kernel/licenses/block-buffer-0.10.4-LICENSE-APACHE +201 -0
  43. package/kernel/licenses/block-buffer-0.10.4-LICENSE-MIT +25 -0
  44. package/kernel/licenses/cfg-if-1.0.5-LICENSE-APACHE +201 -0
  45. package/kernel/licenses/cfg-if-1.0.5-LICENSE-MIT +25 -0
  46. package/kernel/licenses/cpufeatures-0.2.17-LICENSE-APACHE +201 -0
  47. package/kernel/licenses/cpufeatures-0.2.17-LICENSE-MIT +25 -0
  48. package/kernel/licenses/crc32fast-1.5.4-LICENSE-APACHE +202 -0
  49. package/kernel/licenses/crc32fast-1.5.4-LICENSE-MIT +21 -0
  50. package/kernel/licenses/crossbeam-deque-0.8.8-LICENSE-APACHE +201 -0
  51. package/kernel/licenses/crossbeam-deque-0.8.8-LICENSE-MIT +27 -0
  52. package/kernel/licenses/crossbeam-epoch-0.9.21-LICENSE-APACHE +201 -0
  53. package/kernel/licenses/crossbeam-epoch-0.9.21-LICENSE-MIT +27 -0
  54. package/kernel/licenses/crossbeam-utils-0.8.23-LICENSE-APACHE +201 -0
  55. package/kernel/licenses/crossbeam-utils-0.8.23-LICENSE-MIT +27 -0
  56. package/kernel/licenses/crypto-common-0.1.7-LICENSE-APACHE +201 -0
  57. package/kernel/licenses/crypto-common-0.1.7-LICENSE-MIT +25 -0
  58. package/kernel/licenses/dependencies.json +618 -0
  59. package/kernel/licenses/digest-0.10.7-LICENSE-APACHE +201 -0
  60. package/kernel/licenses/digest-0.10.7-LICENSE-MIT +25 -0
  61. package/kernel/licenses/dyn-clone-1.0.20-LICENSE-APACHE +176 -0
  62. package/kernel/licenses/dyn-clone-1.0.20-LICENSE-MIT +23 -0
  63. package/kernel/licenses/either-1.19.0-LICENSE-APACHE +201 -0
  64. package/kernel/licenses/either-1.19.0-LICENSE-MIT +25 -0
  65. package/kernel/licenses/equivalent-1.0.3-LICENSE-APACHE +201 -0
  66. package/kernel/licenses/equivalent-1.0.3-LICENSE-MIT +25 -0
  67. package/kernel/licenses/fdeflate-0.3.7-LICENSE-APACHE +177 -0
  68. package/kernel/licenses/fdeflate-0.3.7-LICENSE-MIT +25 -0
  69. package/kernel/licenses/flate2-1.1.10-LICENSE-APACHE +201 -0
  70. package/kernel/licenses/flate2-1.1.10-LICENSE-MIT +25 -0
  71. package/kernel/licenses/foldhash-0.2.0-LICENSE +19 -0
  72. package/kernel/licenses/generic-array-0.14.7-LICENSE +21 -0
  73. package/kernel/licenses/hashbrown-0.16.1-LICENSE-APACHE +201 -0
  74. package/kernel/licenses/hashbrown-0.16.1-LICENSE-MIT +25 -0
  75. package/kernel/licenses/itoa-1.0.18-LICENSE-APACHE +176 -0
  76. package/kernel/licenses/itoa-1.0.18-LICENSE-MIT +23 -0
  77. package/kernel/licenses/libc-0.2.191-LICENSE-APACHE +176 -0
  78. package/kernel/licenses/libc-0.2.191-LICENSE-MIT +25 -0
  79. package/kernel/licenses/memchr-2.8.3-COPYING +3 -0
  80. package/kernel/licenses/memchr-2.8.3-LICENSE-MIT +21 -0
  81. package/kernel/licenses/miniz_oxide-0.8.9-LICENSE +25 -0
  82. package/kernel/licenses/miniz_oxide-0.8.9-LICENSE-APACHE.md +177 -0
  83. package/kernel/licenses/miniz_oxide-0.8.9-LICENSE-MIT.md +24 -0
  84. package/kernel/licenses/miniz_oxide-0.8.9-LICENSE-ZLIB.md +14 -0
  85. package/kernel/licenses/miniz_oxide-0.9.1-LICENSE +25 -0
  86. package/kernel/licenses/miniz_oxide-0.9.1-LICENSE-APACHE.md +177 -0
  87. package/kernel/licenses/miniz_oxide-0.9.1-LICENSE-MIT.md +24 -0
  88. package/kernel/licenses/miniz_oxide-0.9.1-LICENSE-ZLIB.md +14 -0
  89. package/kernel/licenses/num-traits-0.2.19-LICENSE-APACHE +201 -0
  90. package/kernel/licenses/num-traits-0.2.19-LICENSE-MIT +25 -0
  91. package/kernel/licenses/png-0.17.16-LICENSE-APACHE +201 -0
  92. package/kernel/licenses/png-0.17.16-LICENSE-MIT +25 -0
  93. package/kernel/licenses/proc-macro2-1.0.107-LICENSE-APACHE +176 -0
  94. package/kernel/licenses/proc-macro2-1.0.107-LICENSE-MIT +23 -0
  95. package/kernel/licenses/quote-1.0.47-LICENSE-APACHE +176 -0
  96. package/kernel/licenses/quote-1.0.47-LICENSE-MIT +23 -0
  97. package/kernel/licenses/rayon-1.12.0-LICENSE-APACHE +201 -0
  98. package/kernel/licenses/rayon-1.12.0-LICENSE-MIT +25 -0
  99. package/kernel/licenses/rayon-core-1.13.0-LICENSE-APACHE +201 -0
  100. package/kernel/licenses/rayon-core-1.13.0-LICENSE-MIT +25 -0
  101. package/kernel/licenses/ref-cast-1.0.27-LICENSE-APACHE +176 -0
  102. package/kernel/licenses/ref-cast-1.0.27-LICENSE-MIT +23 -0
  103. package/kernel/licenses/ref-cast-impl-1.0.27-LICENSE-APACHE +176 -0
  104. package/kernel/licenses/ref-cast-impl-1.0.27-LICENSE-MIT +23 -0
  105. package/kernel/licenses/robust-1.2.0-LICENSE-APACHE +201 -0
  106. package/kernel/licenses/robust-1.2.0-LICENSE-MIT +26 -0
  107. package/kernel/licenses/schemars-1.2.3-LICENSE +21 -0
  108. package/kernel/licenses/schemars_derive-1.2.3-LICENSE +21 -0
  109. package/kernel/licenses/serde-1.0.229-LICENSE-APACHE +176 -0
  110. package/kernel/licenses/serde-1.0.229-LICENSE-MIT +23 -0
  111. package/kernel/licenses/serde_core-1.0.229-LICENSE-APACHE +176 -0
  112. package/kernel/licenses/serde_core-1.0.229-LICENSE-MIT +23 -0
  113. package/kernel/licenses/serde_derive-1.0.229-LICENSE-APACHE +176 -0
  114. package/kernel/licenses/serde_derive-1.0.229-LICENSE-MIT +23 -0
  115. package/kernel/licenses/serde_derive_internals-0.30.0-LICENSE-APACHE +176 -0
  116. package/kernel/licenses/serde_derive_internals-0.30.0-LICENSE-MIT +23 -0
  117. package/kernel/licenses/serde_json-1.0.154-LICENSE-APACHE +176 -0
  118. package/kernel/licenses/serde_json-1.0.154-LICENSE-MIT +23 -0
  119. package/kernel/licenses/sha2-0.10.9-LICENSE-APACHE +201 -0
  120. package/kernel/licenses/sha2-0.10.9-LICENSE-MIT +27 -0
  121. package/kernel/licenses/simd-adler32-0.3.10-LICENSE.md +21 -0
  122. package/kernel/licenses/smallvec-1.16.4-LICENSE-APACHE +201 -0
  123. package/kernel/licenses/smallvec-1.16.4-LICENSE-MIT +25 -0
  124. package/kernel/licenses/solidcore-1.0.1-LICENSE +203 -0
  125. package/kernel/licenses/solidcore-1.0.1-NOTICE +30 -0
  126. package/kernel/licenses/solidcore-ATTRIBUTION.md +92 -0
  127. package/kernel/licenses/solidcore-LICENSE +203 -0
  128. package/kernel/licenses/solidcore-NOTICE +30 -0
  129. package/kernel/licenses/solidcore-convert-0.1.0-ATTRIBUTION.md +92 -0
  130. package/kernel/licenses/solidcore-convert-0.1.0-LICENSE +203 -0
  131. package/kernel/licenses/solidcore-convert-0.1.0-NOTICE +30 -0
  132. package/kernel/licenses/solidcore-record-0.1.0-ATTRIBUTION.md +92 -0
  133. package/kernel/licenses/solidcore-record-0.1.0-LICENSE +203 -0
  134. package/kernel/licenses/solidcore-record-0.1.0-NOTICE +30 -0
  135. package/kernel/licenses/solidcore-tess-0.1.0-ATTRIBUTION.md +92 -0
  136. package/kernel/licenses/solidcore-tess-0.1.0-LICENSE +203 -0
  137. package/kernel/licenses/solidcore-tess-0.1.0-NOTICE +30 -0
  138. package/kernel/licenses/spade-2.15.1-LICENSE-APACHE +202 -0
  139. package/kernel/licenses/spade-2.15.1-LICENSE-MIT +25 -0
  140. package/kernel/licenses/step-brep-0.1.0-ATTRIBUTION.md +92 -0
  141. package/kernel/licenses/step-brep-0.1.0-LICENSE +203 -0
  142. package/kernel/licenses/step-brep-0.1.0-NOTICE +30 -0
  143. package/kernel/licenses/step-export-0.1.0-ATTRIBUTION.md +92 -0
  144. package/kernel/licenses/step-export-0.1.0-LICENSE +203 -0
  145. package/kernel/licenses/step-export-0.1.0-NOTICE +30 -0
  146. package/kernel/licenses/step-import-0.1.0-ATTRIBUTION.md +92 -0
  147. package/kernel/licenses/step-import-0.1.0-LICENSE +203 -0
  148. package/kernel/licenses/step-import-0.1.0-NOTICE +30 -0
  149. package/kernel/licenses/syn-3.0.9-LICENSE-APACHE +176 -0
  150. package/kernel/licenses/syn-3.0.9-LICENSE-MIT +23 -0
  151. package/kernel/licenses/thiserror-2.0.21-LICENSE-APACHE +176 -0
  152. package/kernel/licenses/thiserror-2.0.21-LICENSE-MIT +23 -0
  153. package/kernel/licenses/thiserror-impl-2.0.21-LICENSE-APACHE +176 -0
  154. package/kernel/licenses/thiserror-impl-2.0.21-LICENSE-MIT +23 -0
  155. package/kernel/licenses/typenum-1.20.1-LICENSE +1 -0
  156. package/kernel/licenses/typenum-1.20.1-LICENSE-APACHE +201 -0
  157. package/kernel/licenses/typenum-1.20.1-LICENSE-MIT +21 -0
  158. package/kernel/licenses/unicode-ident-1.0.27-LICENSE-APACHE +176 -0
  159. package/kernel/licenses/unicode-ident-1.0.27-LICENSE-MIT +23 -0
  160. package/kernel/licenses/unicode-ident-1.0.27-LICENSE-UNICODE +39 -0
  161. package/kernel/licenses/version_check-0.9.5-LICENSE-APACHE +201 -0
  162. package/kernel/licenses/version_check-0.9.5-LICENSE-MIT +19 -0
  163. package/kernel/licenses/zlib-rs-0.6.8-LICENSE +19 -0
  164. package/kernel/licenses/zmij-1.0.23-LICENSE-MIT +23 -0
  165. package/kernel/native/darwin-arm64/agent-cad +4 -0
  166. package/kernel/native/darwin-arm64/manifest.json +6 -0
  167. package/kernel/native/linux-arm64/agent-cad +4 -0
  168. package/kernel/native/linux-arm64/manifest.json +6 -0
  169. package/kernel/native/linux-x64/agent-cad +4 -0
  170. package/kernel/native/linux-x64/manifest.json +6 -0
  171. package/kernel/release.json +8 -0
  172. package/kernel/schemas/model.schema.json +4080 -0
  173. package/package.json +59 -4
  174. package/scripts/check-release.mjs +24 -0
  175. package/skills/colocad/SKILL.md +17 -0
  176. package/skills/colocad/assets/angle-bracket.json +39 -0
  177. package/skills/colocad/assets/ball.json +16 -0
  178. package/skills/colocad/assets/block.json +18 -0
  179. package/skills/colocad/assets/open-housing.json +35 -0
  180. package/skills/colocad/assets/pin.json +18 -0
  181. package/skills/colocad/assets/plate-grid.json +34 -0
  182. package/skills/colocad/assets/sleeve.json +19 -0
  183. package/skills/colocad/assets/taper.json +20 -0
  184. package/skills/colocad/references/quick-build.md +44 -0
  185. package/skills/colocad/scripts/assembly.mjs +3 -0
  186. package/skills/colocad/scripts/build.mjs +54 -0
  187. package/solidworks/managed/Colocad.SolidWorks.deps.json +23 -0
  188. package/solidworks/managed/Colocad.SolidWorks.dll +0 -0
  189. package/solidworks/managed/Colocad.SolidWorks.runtimeconfig.json +13 -0
  190. package/src/build.mjs +69 -0
  191. package/src/index.d.mts +67 -0
  192. package/src/index.mjs +4 -0
  193. package/src/solidworks.mjs +65 -0
  194. package/src/tree.mjs +199 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Agent CAD contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/NOTICE.md ADDED
@@ -0,0 +1,5 @@
1
+ # Notices
2
+
3
+ Colocad and the included Agent CAD application code are distributed under the MIT license. The Rust application builds against SolidCore at revision bff1569a4c3347ed9af67faab71578cadf84fde2. SolidCore includes work derived from NVIDIA USD BRep / SMLib. The kernel's Apache-2.0 license, notices, attribution and licenses of Rust dependencies ship in `kernel/licenses`. Source provenance is also recorded in `third_party`.
4
+
5
+ The .NET author references SOLIDWORKS 2024 interop APIs. SOLIDWORKS is a trademark of its respective owner. A local licensed installation provides the proprietary COM application and its interop assemblies. The package contains Colocad's own managed assembly and source in the repository. The experimental file-format investigation uses the independently licensed cadmpeg project at d77e2dd2a9d154e7b432afb022c147864f2618bb.
package/README.md CHANGED
@@ -1,3 +1,132 @@
1
- # Temporary Holding Version
1
+ # colocad
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [中文说明](README.zh-CN.md) · [npm package](https://www.npmjs.com/package/@coloopx/colocad) · [Download the offline comparison](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html)
4
+
5
+ Generate a mechanical part from a JSON feature tree, export an exact STEP solid, and give an agent a PNG or 3D preview to inspect. **The npm package ships the compiled Rust CAD kernel.** The agent and harness call it locally in the same sandbox through the Node CLI or TypeScript API. No Python, Rust toolchain, network or separate service is required to build a part after installation.
6
+
7
+ ## How many tendon hands can an agent deliver in 100 seconds?
8
+
9
+ **colocad delivered 44 complete revisions to build123d’s 33 (+33.3%), with 57.1% lower peak sampled sandbox memory.** Both tools rebuilt and assembled the same 43-solid hand at each revision. Each tick marks a complete STEP handed off to storage.
10
+
11
+ ![10× replay of tendon-hand modeling and assembly: 44 vs. 33 STEP deliveries; sampled sandbox memory peaks at 130.9 vs. 304.9 MiB.](showcase/tendon-hand/window/hand-window-peak-en.gif)
12
+
13
+ The GIF shows the **highest memory sampled so far** for each tool on the same 0–512 MiB scale. For actual usage between builds, see the [instantaneous-memory replay (MP4)](https://github.com/Coloopx/colocad/raw/refs/heads/main/showcase/tendon-hand/window/hand-window-en.mp4) or the [timestamped samples](showcase/tendon-hand/evidence/window-optimized.json).
14
+
15
+ | Same revision queue, 1 vCPU / 512 MiB | Optimized colocad | build123d |
16
+ |---|---:|---:|
17
+ | Complete hands delivered in 100 s | **44** | 33 |
18
+ | First STEP | **2.223 s** | 3.010 s |
19
+ | Median job time on the same first 33 inputs | **2.234 s** | 2.855 s |
20
+ | Highest sampled cgroup memory over the 100 s window | **130.9 MiB** | 304.9 MiB |
21
+
22
+ One measured window per backend, with a new CAD process for each revision. The original run used the alpha.2 SDK and the optimized Linux arm64 kernel now bundled in alpha.3. Memory samples taken about every 25 ms include subprocesses, tmpfs and charged file cache. Every counted STEP reopened successfully. [Measurement method](showcase/tendon-hand/window/README.md) · [Detailed build and single-call replay](showcase/tendon-hand/assembly-performance.md)
23
+
24
+ The static scorecard below uses the **published alpha.2 binary**. With fresh tool processes the sensor rail and manifold reached STEP 22.0× and 12.9× faster than build123d, using 7.7% and 8.0% of its peak memory.
25
+
26
+ <details>
27
+ <summary>See the static comparison across four workloads</summary>
28
+
29
+ ![Time to STEP and peak cgroup memory across four workloads. Shorter bars are better.](docs/benchmarks/time-to-step.svg)
30
+
31
+ </details>
32
+
33
+ | Deliverable | Time to STEP: colocad / build123d | Speedup¹ | Peak memory: colocad / build123d | Share of build123d peak |
34
+ | :--- | ---: | ---: | ---: | ---: |
35
+ | Sensor rail | 113 / 2,485 ms | **22.0×** | 20.0 / 259.3 MiB | **7.7%** |
36
+ | Port manifold | 230 / 2,963 ms | **12.9×** | 20.7 / 258.7 MiB | **8.0%** |
37
+ | Tendon-hand proximal link | 259 / 2,244 ms | **8.6×** | 21.4 / 260.1 MiB | **8.2%** |
38
+ | Complete 43-solid hand | 3,952 / 3,293 ms | **0.83×** | 52.7 / 271.3 MiB | **19.4%** |
39
+
40
+ ¹ build123d time divided by colocad time from unrounded observations. Same Linux arm64 image, 1 vCPU, 512 MiB. Five fresh processes and cgroups per part and backend after warm-up. Time is the median wall clock including startup, imports, modeling, backend checks and STEP export. Memory is the maximum measured cgroup peak; charged pages, temporary outputs and tool descendants count. Installation, container startup, previews, inference and a resident agent are excluded.
41
+
42
+ [Rail/manifold samples](docs/benchmarks/runs.json) · [Finger/hand samples](showcase/tendon-hand/evidence/scope.json) · [Four-view hand study and CAD downloads](showcase/tendon-hand/README.md) · [Offline scorecard](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/time-to-step.html)
43
+
44
+ **Historical alpha.2 result.** in a separate 100-second sweep of complete hand revisions, colocad delivered 24 STEPs to build123d’s 30. Every counted file reopened as a valid 43-solid assembly. [Timestamped outputs and paired geometry checks](showcase/tendon-hand/evidence/window.json)
45
+
46
+ ## SDK, CLI or skill?
47
+
48
+ Install with `npm install @coloopx/colocad@0.1.0-alpha.3`. This version bundles the optimized assembly kernel and the complete agent skill. The skill lives at `node_modules/@coloopx/colocad/skills/colocad/`. Point your harness at its `SKILL.md` or copy the whole directory into your agent’s skill collection.
49
+
50
+ For a dimensioned part, try “Make a 100 × 50 × 6 mm plate with a centered 3 × 2 grid of Ø6 through-holes on 32 × 30 mm pitches.” The skill includes editable stock, hole grids, sleeves, brackets and open housings. [Quick-build commands and examples](skills/colocad/references/quick-build.md)
51
+
52
+ - **In an application or harness:** call `build(tree, newDir, { preview: true })` in the SDK. Use `CadClient.build(model)` for named multi-solid assemblies.
53
+ - **In a shell or agent tool call:** install `npm install @coloopx/colocad@0.1.0-alpha.3`. Run `./node_modules/.bin/colocad plan tree.json`, then `./node_modules/.bin/colocad build tree.json ./new-part --preview`. Open `new-part/part/model.step`.
54
+ - **From drawings with an agent:** install the [colocad skill](skills/colocad/SKILL.md). Start the next turn with “Use `$colocad` to reconstruct these four views, export STEP, and flag any internal details you inferred.” [Installation and assembly replay](showcase/tendon-hand/README.md#try-it-with-your-agent).
55
+
56
+ ## What the two STEP writers produced
57
+
58
+ ![Two independently modeled STEP pairs. Top: a sensor rail with three through-slots. Bottom: a manifold with four blind bores and a rectangular pocket. Colocad on the left; build123d on the right.](docs/benchmarks/step-comparison.png)
59
+
60
+ Each backend modeled the part from the same parameters. The images use the exported STEPs, the same mesher and camera. OCCT reopened each file as **one valid solid**. Both rail exports had 22 faces and 56 edges; both manifold exports had 27 faces and 54 edges. The two directional boolean differences measured **0 mm³** in both cases (boolean tolerance: 0.000001 mm). [Geometry checks](docs/benchmarks/step-checks.json)
61
+
62
+ On the manifold, build123d’s modeling phase alone was **43.8 ms** to colocad’s **53.7 ms**, while build123d import alone took **2.45 s**. The table measures a fresh tool call, not the speed of an isolated boolean operation. [Stage timings and reproduction](benchmarks/readme/README.md)
63
+
64
+ ### When the agent only changes the camera
65
+
66
+ The first preview saves a display mesh. For a second view of unchanged geometry, the kernel SDK can load that mesh instead of rebuilding the solid or triangulating it again. Here are five-run medians for the same **top view**, comparing two paths inside colocad:
67
+
68
+ | Part | Rebuild part + render | Render from saved mesh | Speedup |
69
+ | :--- | ---: | ---: | ---: |
70
+ | Sensor rail | 108.8 ms | 19.4 ms | **5.6×** |
71
+ | Port manifold | 223.8 ms | 13.3 ms | **16.8×** |
72
+
73
+ The PNG, GLB and STL from both paths matched byte for byte on every pair. This test starts with the SDK already loaded and includes native process startup and display output. A geometry edit needs a new revision. [Preview measurements and hashes](docs/benchmarks/preview-runs.json)
74
+
75
+ ## What ships
76
+
77
+ | In the [npm tarball](https://www.npmjs.com/package/@coloopx/colocad) | In the [source repository](https://github.com/Coloopx/colocad) |
78
+ | :--- | :--- |
79
+ | Agent skill, CLI, JavaScript API, TypeScript declarations and precompiled Rust executables for **Linux x64, Linux arm64 and macOS arm64**. Node.js 22+. | [Rust CAD source](crates/agent-cad/src), [TypeScript kernel SDK](kernel/src), [feature compiler](src/tree.mjs), tests and [pinned SolidCore dependency](third_party/solidcore.lock.json). |
80
+
81
+ For example, on Linux arm64 the CLI launches `node_modules/@coloopx/colocad/kernel/native/linux-arm64/agent-cad`. The tarball contains the executable; the Rust `.rs` files are in the repository.
82
+
83
+ **Alpha status.** Linux supports parametric edits, STEP and PNG/GLB/STL export. Direct generation of a complex, editable SOLIDWORKS part on Linux is still experimental. The optional Windows author compiles against the SOLIDWORKS 2024 interop API; a licensed native rebuild has not been verified. See the [native author](#native-solidworks-author-experimental) and [validation notes](docs/validation.md).
84
+
85
+ ## Run the examples
86
+
87
+ ```sh
88
+ npm install @coloopx/colocad@alpha
89
+ npx colocad build node_modules/@coloopx/colocad/examples/manifold.json ./manifold --preview
90
+ npx colocad build node_modules/@coloopx/colocad/examples/sensor-rail.json ./rail
91
+ ```
92
+
93
+ The manifold contains a six-sided extrusion, a blind circular cut, an upper-rim fillet, a four-instance pattern referencing the earlier cut, and a rectangular pocket. The sensor rail uses a different sketch, feature order and pattern direction. Both run through the same compiler. The pattern count includes the seed.
94
+
95
+ Each call requires a new output directory. The `part/` subdirectory holds `model.step`, `feature-tree.json`, a kernel report, and `native-job.json`. With `--preview` it also contains PNG, STL and GLB files. The native job stores the ordered feature definitions, resolved inputs and reference geometry measurements.
96
+
97
+ ```js
98
+ import { readFile } from 'node:fs/promises';
99
+ import { build } from '@coloopx/colocad';
100
+
101
+ const tree = JSON.parse(await readFile('./node_modules/@coloopx/colocad/examples/manifold.json', 'utf8'));
102
+ await build(tree, './original');
103
+ tree.parameters.instances = 3;
104
+ const edited = await build(tree, './edited');
105
+ console.log(edited.geometry.volume_mm3);
106
+ ```
107
+
108
+ All coordinates and lengths are in mm. The first extrusion creates a solid. Further extrusions add material and cuts remove material along +Z from a sketch at `startZ` (default 0). Profiles can be rectangles, circles or polygons. Fillets select edges on a specified Z plane and require the declared match count. A linear pattern refers to an earlier extrusion or cut by ID, with X/Y direction, positive pitch and instance count. IDs are unique, case-insensitively. A scalar is a finite number or a reference such as `{"param":"thickness"}`. The public TypeScript declaration defines the full input.
109
+
110
+ The kernel API at `@coloopx/colocad/kernel` also exposes the lower-level geometry operations, STEP import, incremental revisions and preview cache. The npm tarball includes Linux arm64/x64 and macOS arm64 executables and dependency licenses. The checked-in sources build the kernel on supported toolchains.
111
+
112
+ ## Native SOLIDWORKS author (experimental)
113
+
114
+ The Windows entry point consumes the same job. It starts a blank part using the application's configured default, builds sketches with native lines and circles, calls extrusion/cut/fillet/pattern APIs and names the resulting features. The fillet uses body edges and the native pattern selects the original seed feature. There are no part-specific model files. Running it requires local Windows, .NET 8 and a licensed SOLIDWORKS installation with a valid default blank part configuration.
115
+
116
+ ```powershell
117
+ colocad solidworks .\manifold\part\native-job.json .\manifold.SLDPRT
118
+ ```
119
+
120
+ Use `COLOCAD_SW_INTEROP` for an alternate directory containing the local SOLIDWORKS interop DLLs. The completion check is designed to save a temporary part, reopen it, verify native types, radius, pattern seed, count, pitch and reference volume, then edit a driving extrusion dimension, rebuild, restore and check it. Only a successful check publishes the output. The current release has **no native runtime pass** for either complex part. The package includes no four-hole template and does not route jobs to another machine.
121
+
122
+ ## Build and verify from source
123
+
124
+ ```sh
125
+ npm run build:kernel
126
+ npm test
127
+ node bin/colocad.mjs build examples/manifold.json ./out/manifold --preview
128
+ ```
129
+
130
+ The first command fetches the pinned SolidCore archive, checks its SHA-256 and builds the local Rust executable. The plain Node tests use the local executable or `AGENT_CAD_BINARY`. The repository includes the TypeScript kernel SDK source and its compiled distribution. To rebuild the .NET author, build `solidworks/Colocad.SolidWorks.csproj` with a .NET 8 SDK and `-p:SWInteropDir=<directory containing the two SOLIDWORKS interop DLLs>`. Copy only Colocad.SolidWorks.dll, its deps.json and runtimeconfig.json to solidworks/managed.
131
+
132
+ Independent OCCT validation is in `test/validation/geometry.py`. It reopens the STEP and checks both volume and whether selected points lie inside the plate, the holes, the recess or the fillet. The measured results and the limits of the native experiment are in [the validation notes](docs/validation.md).
@@ -0,0 +1,100 @@
1
+ # colocad
2
+
3
+ [English](README.md) · [npm 包](https://www.npmjs.com/package/@coloopx/colocad) · [下载单文件对比报告:含四份 STEP](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html)
4
+
5
+ 让沙箱内的 agent 用 JSON 描述可改参的机械零件,输出 STEP 实体、PNG 预览和 GLB/STL 网格。**npm 包自带编译好的 Rust CAD 内核**:Linux x64、Linux arm64 和 macOS arm64 各一份。agent 和 harness 在同一沙箱里调用 Node CLI 或 TypeScript API,CLI 直接启动本地 Rust 程序。安装后建模不需要网络、Python、Rust 工具链或额外服务。[Rust 源码](crates/agent-cad/src)和[内核依赖版本](third_party/solidcore.lock.json)在本仓库。
6
+
7
+ ## 100 秒能交付多少版绳驱灵巧手?
8
+
9
+ **colocad 交付 44 版,build123d 交付 33 版:交付量多 33.3%,采样峰值内存低 57.1%。** 两边按同一组参数逐版建模、装配。每条刻线代表一份含 43 个实体的整手 STEP 已写入持久存储。
10
+
11
+ ![绳驱灵巧手建模与装配的 10 倍速回放:两边交付 44 和 33 版,采样峰值内存分别为 130.9 和 304.9 MiB。](showcase/tendon-hand/window/hand-window-peak-en.gif)
12
+
13
+ 动图底部显示两边**从开始到当前时刻采到的最高内存**,共用 0–512 MiB 刻度。要看每次建模之间内存如何回落,可打开[瞬时内存回放(MP4)](https://github.com/Coloopx/colocad/raw/refs/heads/main/showcase/tendon-hand/window/hand-window-zh-CN.mp4)或[原始采样](showcase/tendon-hand/evidence/window-optimized.json)。
14
+
15
+ | 同一改参队列,1 vCPU / 512 MiB | colocad 优化内核 | build123d |
16
+ |---|---:|---:|
17
+ | 100 秒内交付的完整整手 | **44 份** | 33 份 |
18
+ | 首份 STEP | **2.223 s** | 3.010 s |
19
+ | 共同前 33 份交付耗时中位数 | **2.234 s** | 2.855 s |
20
+ | 连续 100 秒内的最高采样内存 | **130.9 MiB** | 304.9 MiB |
21
+
22
+ 各运行一个真实窗口,每版新起 CAD 进程。这次原始记录使用 alpha.2 SDK 和优化后的 Linux arm64 内核。alpha.3 已内置同一份二进制。内存约每 25 ms 采样,包含子进程、临时文件和计入本容器的文件缓存。两边计入的 STEP 都已独立回读。[单文件回放与 STEP 下载](https://github.com/Coloopx/colocad/raw/refs/heads/main/showcase/tendon-hand/window/hand-window.html) · [建模细节与单次原速回放](showcase/tendon-hand/assembly-performance.md)
23
+
24
+ 以下静态表记录 npm **0.1.0-alpha.2 自带内核**的历史基线。新进程交付导轨和歧管分别快 22.0× 和 12.9×,峰值内存分别为 build123d 的 7.7% 和 8.0%。
25
+
26
+ <details>
27
+ <summary>查看四种任务的静态对照图</summary>
28
+
29
+ ![四种任务的交付 STEP 耗时与实测峰值内存](docs/benchmarks/time-to-step.zh-CN.svg)
30
+
31
+ </details>
32
+
33
+ | 独立交付物 | 首份 STEP:colocad / build123d | 交付速度比¹ | 沙箱峰值:colocad / build123d | 内存占对方 |
34
+ |---|---:|---:|---:|---:|
35
+ | 三槽导轨 | 113 / 2,485 ms | **22.0×** | 20.0 / 259.3 MiB | **7.7%** |
36
+ | 四盲孔歧管 | 230 / 2,963 ms | **12.9×** | 20.7 / 258.7 MiB | **8.0%** |
37
+ | 绳驱手近节指骨 | 259 / 2,244 ms | **8.6×** | 21.4 / 260.1 MiB | **8.2%** |
38
+ | 43 实体整手 | 3,952 / 3,293 ms | **0.83×** | 52.7 / 271.3 MiB | **19.4%** |
39
+
40
+ ¹ 速度比为 build123d 用时 ÷ colocad 用时,按未取整的读数计算。Linux arm64、1 vCPU、512 MiB。每组预热后交替运行五轮,**耗时取中位数,内存取五轮容器 cgroup 峰值最大值**。计入启动、导入、建模、后端自身的检查及 STEP 导出;不含安装、容器启动、预览、模型推理或常驻 agent。单件和整手使用各自对应的公开接口。
41
+
42
+ [原始读数:导轨与歧管](docs/benchmarks/runs.json) · [原始读数:指骨与整手](showcase/tendon-hand/evidence/scope.json) · [四视图、可编辑整手和 STEP](showcase/tendon-hand/README.md) · [离线数据卡](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/time-to-step.html)
43
+
44
+ **旧版整手基线。** 另一项 100 秒、按顺序改参的实测中,colocad 交付 24 份整手 STEP,build123d 交付 30 份;每份都是完整的 43 个实体,已逐件回读。[两端交付时间戳与几何核对](showcase/tendon-hand/evidence/window.json)
45
+
46
+ ## SDK、CLI、skill 怎么选?
47
+
48
+ 运行 `npm install @coloopx/colocad@0.1.0-alpha.3` 即可安装优化后的装配内核和完整 skill。沙箱内的 harness 可加载 `node_modules/@coloopx/colocad/skills/colocad/SKILL.md`,也可以把整个 `colocad` skill 目录复制到 agent 的技能目录。
49
+
50
+ 常见机械件可以让 agent 直接按尺寸搭建。例如「做一块 100 × 50 × 6 mm 的安装板,钻 3 × 2 个 Ø6 通孔,两向孔距 32 和 30 mm」。skill 自带可改参的孔阵列、轴套、角码、开口壳和四种基础实体。参见[基础形状与结构的命令示例](skills/colocad/references/quick-build.md)。
51
+
52
+ - **应用或 harness 集成:** 进程里直接调用 SDK 的 `build(tree, newDir, { preview: true })`;多实体装配用 `CadClient.build(model)`。
53
+ - **终端或沙箱 agent:** 安装 `npm install @coloopx/colocad@0.1.0-alpha.3`;用 `./node_modules/.bin/colocad plan tree.json` 检查特征,再用 `./node_modules/.bin/colocad build tree.json ./new-part --preview`。成品在 `new-part/part/model.step`。全程在同一沙箱内。
54
+ - **从多视图交给 agent:** 从 [skills/colocad](skills/colocad/SKILL.md) 安装 skill;下个回合输入「用 `$colocad` 读这四张图,生成可编辑模型和 STEP,并标出推断的内部结构」。[完整安装命令、SDK 装配示例和重放步骤](showcase/tendon-hand/README.md#try-it-with-your-agent)。
55
+
56
+ 以 Linux arm64 为例,安装后可执行文件就在 `node_modules/@coloopx/colocad/kernel/native/linux-arm64/agent-cad`。npm 分发编译产物;要读或修改 `.rs` 源文件,请用上面的 GitHub 源码链接。
57
+
58
+ ## 两个建模后端做出来的东西一样吗?
59
+
60
+ ![左列 colocad,右列 build123d。上排为三槽传感器导轨,下排从底部看四盲孔歧管,可见孔列和矩形浅槽。](docs/benchmarks/step-comparison.png)
61
+
62
+ 左右两列分别从相同参数独立建模、导出 STEP,再用同一套 OCCT 三角化参数、相机和光照出图。四份 STEP 回读都是有效的单实体。导轨各有 22 个面、56 条边;歧管各有 27 个面、54 条边。两个零件分别做 A−B、B−A,测得差集体积均为 **0 mm³**(布尔容差 0.000001 mm)。[逐件几何核对](docs/benchmarks/step-checks.json)
63
+
64
+ 只看歧管几何阶段,build123d 是 43.8 ms,colocad 是 53.7 ms;build123d 导入则用了 2.45 s。端到端提速不能当作纯几何运算提速。[分阶段数据与复现方法](benchmarks/readme/README.md)
65
+
66
+ ## 如果 agent 只是转动视角呢?
67
+
68
+ 首次预览会保存网格。同一个零件从等轴视图切到俯视图,SDK 可以用 `observeArtifact` 重新出图,跳过精确建模和三角化。同一版 colocad 在同样沙箱预算下得到以下五轮中位数:
69
+
70
+ | 切到俯视图 | 完整重建并出图 | 复用网格出图 | 加速比 |
71
+ | :--- | ---: | ---: | ---: |
72
+ | 导轨 | 108.8 ms | 19.4 ms | **5.6×** |
73
+ | 歧管 | 223.8 ms | 13.3 ms | **16.8×** |
74
+
75
+ 每对输出的 PNG、GLB、STL 三个文件均逐字节相同。这一组只比较 colocad 的两条路径;SDK 已加载,计时包括启动本地 Rust 进程和写出显示文件。改几何参数需要生成新版本。[预览耗时和文件哈希](docs/benchmarks/preview-runs.json)
76
+
77
+ ## 试跑并改参
78
+
79
+ 需要 Node.js 22+。输出目录必须是新目录。
80
+
81
+ ```sh
82
+ npm install @coloopx/colocad@0.1.0-alpha.3
83
+ npx colocad build node_modules/@coloopx/colocad/examples/manifold.json ./manifold --preview
84
+ ```
85
+
86
+ 打开 `manifold/part/model.step` 检查实体;`preview.png`、`model.glb` 和 `model.stl` 用于查看。歧管由六边形拉伸、盲孔切除、上缘圆角、引用种子孔的线性阵列和矩形浅槽构成。将 `instances` 从 4 改到 3,少切一个 Ø6 × 8 mm 的盲孔,实测恢复材料 **226.195 mm³**,与圆柱体积一致。[验证记录](docs/evidence/scoped-runner.json)
87
+
88
+ ```js
89
+ import { readFile } from 'node:fs/promises';
90
+ import { build } from '@coloopx/colocad';
91
+
92
+ const tree = JSON.parse(await readFile('./node_modules/@coloopx/colocad/examples/manifold.json', 'utf8'));
93
+ tree.parameters.instances = 3;
94
+ const result = await build(tree, './three-port-manifold', { preview: true });
95
+ console.log(result.step);
96
+ ```
97
+
98
+ 公开特征接口支持矩形、圆和多边形草图拉伸、切除、按 Z 平面选边的定半径圆角,以及沿 X/Y 的拉伸或切除阵列。[类型定义](src/index.d.mts) · [更底层的内核 API](kernel/src/client.ts)
99
+
100
+ **交付边界:** Linux 已验证 STEP、网格和改参。Linux 直接生成复杂、可在 SOLIDWORKS 里编辑和重建的原生 `.SLDPRT` 尚未完成。仓库中的 Windows 作者程序已针对 SOLIDWORKS 2024 接口编译,尚未在有授权的 SOLIDWORKS 上完成回读重建。[验证说明](docs/validation.md) · [从源码构建](README.md#build-and-verify-from-source)
@@ -0,0 +1,32 @@
1
+ #!/usr/bin/env node
2
+ import { readFile } from "node:fs/promises";
3
+ import { compileTree, build } from "../src/index.mjs";
4
+ import { writeSolidWorks } from "../src/solidworks.mjs";
5
+ const [cmd, input, output, ...flags] = process.argv.slice(2);
6
+ const help =
7
+ "colocad build TREE.json NEW_DIRECTORY [--preview]\ncolocad plan TREE.json\ncolocad solidworks NATIVE-JOB.json NEW_FILE.SLDPRT";
8
+ try {
9
+ if (cmd === "--help" || cmd === "-h" || !cmd) console.log(help);
10
+ else {
11
+ if (!input || !["plan", "build", "solidworks"].includes(cmd))
12
+ throw Error(help);
13
+ const raw = await readFile(input);
14
+ if (raw.length > 2 * 1024 * 1024) throw Error("Input exceeds 2 MiB");
15
+ const spec = JSON.parse(raw.toString("utf8"));
16
+ let res;
17
+ if (cmd === "plan" && !output) res = compileTree(spec);
18
+ else if (
19
+ cmd === "build" &&
20
+ output &&
21
+ (flags.length === 0 || (flags.length === 1 && flags[0] === "--preview"))
22
+ )
23
+ res = await build(spec, output, { preview: flags.length > 0 });
24
+ else if (cmd === "solidworks" && output && !flags.length)
25
+ res = await writeSolidWorks(spec, output);
26
+ else throw Error(help);
27
+ console.log(JSON.stringify(res));
28
+ }
29
+ } catch (e) {
30
+ console.error(JSON.stringify({ error: e.message }));
31
+ process.exitCode = 1;
32
+ }
@@ -0,0 +1,11 @@
1
+ {
2
+ "format":"colocad/1","units":"mm",
3
+ "parameters":{"thickness":12,"pocketRadius":3,"pitch":18,"instances":4,"rimRadius":1.2},
4
+ "features":[
5
+ {"id":"Mount","op":"extrude","profile":{"kind":"polygon","points":[[0,0],[83,0],[90,7],[90,38],[83,45],[0,45]]},"depth":{"param":"thickness"}},
6
+ {"id":"Port","op":"cut","profile":{"kind":"circle","center":[14,12],"radius":{"param":"pocketRadius"}},"depth":8},
7
+ {"id":"Rim","op":"fillet","edges":{"z":{"param":"thickness"},"count":6},"radius":{"param":"rimRadius"}},
8
+ {"id":"PortRow","op":"linearPattern","seed":"Port","axis":"x","pitch":{"param":"pitch"},"count":{"param":"instances"}},
9
+ {"id":"Channel","op":"cut","profile":{"kind":"rectangle","center":[43,32],"size":[48,8]},"depth":4}
10
+ ]
11
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "format":"colocad/1","units":"mm","parameters":{"copies":3,"step":19},
3
+ "features":[
4
+ {"id":"Rail","op":"extrude","profile":{"kind":"rectangle","center":[0,22],"size":[30,66]},"depth":9},
5
+ {"id":"EdgeRound","op":"fillet","edges":{"z":9,"count":4},"radius":0.8},
6
+ {"id":"Slot","op":"cut","profile":{"kind":"rectangle","center":[0,3],"size":[9,5]},"depth":10},
7
+ {"id":"Slots","op":"linearPattern","seed":"Slot","axis":"y","pitch":{"param":"step"},"count":{"param":"copies"}}
8
+ ]
9
+ }
package/kernel/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Agent CAD contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,3 @@
1
+ import type { Config, Receipt } from './types.js';
2
+ /** Publish a new revision on success; remove failed jobs even if validation throws. */
3
+ export declare function artifactJob(config: Config, prefix: string, action: (job: string, destination: string) => Promise<Receipt>): Promise<Receipt>;
@@ -0,0 +1,19 @@
1
+ import { mkdir, mkdtemp, rm } from 'node:fs/promises';
2
+ import { resolve, join } from 'node:path';
3
+ /** Publish a new revision on success; remove failed jobs even if validation throws. */
4
+ export async function artifactJob(config, prefix, action) {
5
+ await mkdir(config.outputRoot, { recursive: true });
6
+ const job = await mkdtemp(join(resolve(config.outputRoot), prefix));
7
+ let keep = false;
8
+ try {
9
+ const result = await action(job, join(job, 'revision'));
10
+ if (!result.ok)
11
+ return result;
12
+ keep = true;
13
+ return { ok: true, data: { ...result.data, artifact_directory: join(job, 'revision') } };
14
+ }
15
+ finally {
16
+ if (!keep)
17
+ await rm(job, { recursive: true, force: true });
18
+ }
19
+ }
@@ -0,0 +1,3 @@
1
+ import type { Model } from './types.js';
2
+ /** Register STEP content under an opaque ID; agents never select filesystem paths. */
3
+ export declare function attachStep(model: Model, id: string, step: string): Model;
@@ -0,0 +1,11 @@
1
+ import { createHash } from 'node:crypto';
2
+ /** Register STEP content under an opaque ID; agents never select filesystem paths. */
3
+ export function attachStep(model, id, step) {
4
+ if (!/^[A-Za-z0-9_-]{1,64}$/.test(id))
5
+ throw Error('invalid asset ID');
6
+ if (Object.hasOwn(model.assets ?? {}, id))
7
+ throw Error('asset ID already exists');
8
+ if (Buffer.byteLength(step) > 24 * 1024 * 1024)
9
+ throw Error('STEP exceeds 24 MiB');
10
+ return { ...structuredClone(model), assets: { ...model.assets, [id]: { step, sha256: createHash('sha256').update(step).digest('hex') } } };
11
+ }
@@ -0,0 +1,2 @@
1
+ /** Configured path, then packaged CAD executable for the current OS and architecture. */
2
+ export declare function resolveBinary(binary?: string): string;
@@ -0,0 +1,14 @@
1
+ import { existsSync } from 'node:fs';
2
+ import { fileURLToPath } from 'node:url';
3
+ import { resolve } from 'node:path';
4
+ /** Configured path, then packaged CAD executable for the current OS and architecture. */
5
+ export function resolveBinary(binary) {
6
+ const configured = binary ?? process.env.AGENT_CAD_BINARY;
7
+ if (configured)
8
+ return resolve(configured);
9
+ const name = process.platform === 'win32' ? 'agent-cad.exe' : 'agent-cad';
10
+ const path = fileURLToPath(new URL(`../native/${process.platform}-${process.arch}/${name}`, import.meta.url));
11
+ if (!existsSync(path))
12
+ throw Error(`No packaged CAD executable for ${process.platform}-${process.arch}; configure binary with a local build`);
13
+ return path;
14
+ }
@@ -0,0 +1,22 @@
1
+ import type { Config, Model, Receipt, PreviewOptions, Sketch } from './types.js';
2
+ export type * from './types.js';
3
+ export { attachStep } from './assets.js';
4
+ /** Local CAD API for the Harness and Agent sharing this sandbox. */
5
+ export declare class CadClient {
6
+ private readonly config;
7
+ private previousRevision?;
8
+ private readonly previewCache;
9
+ constructor(config: Config);
10
+ capabilities(): Promise<Receipt>;
11
+ schema(): Promise<Receipt>;
12
+ validate(model: Model): Promise<Receipt>;
13
+ solveSketch(sketch: Sketch, parameters?: Record<string, number>): Promise<Receipt>;
14
+ inspectStep(model: Model, asset: string): Promise<Receipt>;
15
+ preview(model: Model, options?: Partial<PreviewOptions>): Promise<Receipt>;
16
+ /** Resume display from a trusted host artifact path, including in a new SDK process. */
17
+ observeArtifact(directory: string, options?: Partial<PreviewOptions>): Promise<Receipt>;
18
+ build(model: Model, previousRevision?: string | undefined): Promise<Receipt>;
19
+ edit(model: Model, parameters: Record<string, number>): Promise<Receipt>;
20
+ inspect(artifactDirectory: string): Promise<Record<string, unknown>>;
21
+ private invoke;
22
+ }
@@ -0,0 +1,99 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { join } from 'node:path';
3
+ import { artifactJob } from './artifacts.js';
4
+ import { resolveBinary } from './binary.js';
5
+ import { execute, receipt, error } from './process.js';
6
+ import { previewKey, readPreviewCache, CacheError } from './preview-cache.js';
7
+ export { attachStep } from './assets.js';
8
+ /** Local CAD API for the Harness and Agent sharing this sandbox. */
9
+ export class CadClient {
10
+ config;
11
+ previousRevision;
12
+ previewCache = new Map();
13
+ constructor(config) {
14
+ this.config = config;
15
+ if (config.runner && config.runner.mode !== 'native')
16
+ throw Error('CAD executes in the current sandbox. Use the sandbox test harness for Docker experiments.');
17
+ if (config.wallMs !== undefined && (!Number.isFinite(config.wallMs) || config.wallMs < 1 || config.wallMs > 120_000)) {
18
+ throw Error('wallMs must be 1..120000');
19
+ }
20
+ }
21
+ async capabilities() { return this.invoke(['capabilities']); }
22
+ async schema() { return this.invoke(['schema']); }
23
+ async validate(model) { return this.invoke(['validate'], model); }
24
+ async solveSketch(sketch, parameters = {}) {
25
+ return this.invoke(['solve-sketch'], { sketch, parameters });
26
+ }
27
+ async inspectStep(model, asset) {
28
+ const source = model.assets?.[asset];
29
+ if (!source)
30
+ return error('ASSET_NOT_FOUND', asset);
31
+ const result = await this.invoke(['inspect-step'], source);
32
+ if (result.ok) {
33
+ const template = result.data.model_template;
34
+ for (const feature of template.features)
35
+ if (feature.op === 'import_step')
36
+ feature.asset = asset;
37
+ result.data.required_asset_id = asset;
38
+ }
39
+ return result;
40
+ }
41
+ async preview(model, options = {}) {
42
+ const next = { ...structuredClone(model), preview: { ...model.preview, ...options } };
43
+ const cached = this.previewCache.get(previewKey(next));
44
+ return cached ? this.observeArtifact(cached, next.preview) : this.build(next);
45
+ }
46
+ /** Resume display from a trusted host artifact path, including in a new SDK process. */
47
+ async observeArtifact(directory, options = {}) {
48
+ try {
49
+ const cached = await readPreviewCache(directory, options);
50
+ return await artifactJob(this.config, 'observe-', async (_job, destination) => {
51
+ const result = await this.invoke(['observe', '--out', destination, '--options', JSON.stringify(cached.options)], undefined, cached.raw);
52
+ if (!result.ok)
53
+ return result;
54
+ if (result.data.source_hash !== cached.sourceHash)
55
+ return error('INVALID_MESH_CACHE', 'cache source revision mismatch');
56
+ return { ok: true, data: { ...result.data, source_artifact_directory: cached.source } };
57
+ });
58
+ }
59
+ catch (cause) {
60
+ return error(cause instanceof CacheError ? cause.code : 'PREVIEW_CACHE_READ_FAILED', String(cause));
61
+ }
62
+ }
63
+ async build(model, previousRevision = this.previousRevision) {
64
+ const checkpoints = previousRevision ? ['--reuse', previousRevision] : ['--checkpoints'];
65
+ const result = await artifactJob(this.config, 'job-', (_job, destination) => this.invoke(['build', '--out', destination, ...checkpoints], model));
66
+ if (result.ok)
67
+ this.previousRevision = result.data.artifact_directory;
68
+ if (result.ok && model.preview && result.data.artifact_sha256?.['preview.mesh.json']) {
69
+ this.previewCache.set(previewKey(model), result.data.artifact_directory);
70
+ if (this.previewCache.size > 16)
71
+ this.previewCache.delete(this.previewCache.keys().next().value);
72
+ }
73
+ return result;
74
+ }
75
+ async edit(model, parameters) {
76
+ for (const [key, value] of Object.entries(parameters)) {
77
+ if (!Object.hasOwn(model.parameters, key))
78
+ return error('UNKNOWN_PARAMETER', key);
79
+ if (!Number.isFinite(value))
80
+ return error('INVALID_PARAMETER', key);
81
+ }
82
+ return this.build({ ...structuredClone(model), parameters: { ...model.parameters, ...parameters } });
83
+ }
84
+ async inspect(artifactDirectory) {
85
+ return JSON.parse(await readFile(join(artifactDirectory, 'report.json'), 'utf8'));
86
+ }
87
+ async invoke(args, model, rawInput) {
88
+ const input = rawInput ?? (model ? JSON.stringify(model) : '');
89
+ if (Buffer.byteLength(input) > 32 * 1024 * 1024)
90
+ return error('RESOURCE_LIMIT', 'input exceeds 32 MiB');
91
+ try {
92
+ const binary = resolveBinary(this.config.binary ?? this.config.runner?.binary);
93
+ return receipt(await execute(binary, args, input, this.config.wallMs ?? 30_000));
94
+ }
95
+ catch (cause) {
96
+ return error('LOCAL_EXECUTION_FAILED', String(cause));
97
+ }
98
+ }
99
+ }
@@ -0,0 +1,19 @@
1
+ import { CadClient } from './client.js';
2
+ import type { Model } from './types.js';
3
+ /** Paths belong to the Harness in the current sandbox. Foreign STEP geometry is imported as an asset. */
4
+ export declare function readModelFile(cad: CadClient, path: string): Promise<Model>;
5
+ /** Export a new file. A STEP with embedModel=true can be reopened and edited from that single file. */
6
+ export declare function writeModelFile(cad: CadClient, model: Model, path: string, options?: {
7
+ embedModel?: boolean;
8
+ }): Promise<{
9
+ path: string;
10
+ bytes: number;
11
+ sha256: string;
12
+ model_hash: string;
13
+ }>;
14
+ export declare function editModelFile(cad: CadClient, source: string, parameters: Record<string, number>, destination: string): Promise<{
15
+ path: string;
16
+ bytes: number;
17
+ sha256: string;
18
+ model_hash: string;
19
+ }>;