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

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 (179) hide show
  1. package/LICENSE +21 -0
  2. package/NOTICE.md +5 -0
  3. package/README.md +53 -2
  4. package/bin/colocad.mjs +32 -0
  5. package/examples/manifold.json +11 -0
  6. package/examples/sensor-rail.json +9 -0
  7. package/kernel/LICENSE +21 -0
  8. package/kernel/dist/artifacts.d.ts +3 -0
  9. package/kernel/dist/artifacts.js +19 -0
  10. package/kernel/dist/assets.d.ts +3 -0
  11. package/kernel/dist/assets.js +11 -0
  12. package/kernel/dist/binary.d.ts +2 -0
  13. package/kernel/dist/binary.js +14 -0
  14. package/kernel/dist/client.d.ts +22 -0
  15. package/kernel/dist/client.js +99 -0
  16. package/kernel/dist/files.d.ts +19 -0
  17. package/kernel/dist/files.js +103 -0
  18. package/kernel/dist/generated.d.ts +707 -0
  19. package/kernel/dist/generated.js +1 -0
  20. package/kernel/dist/helpers.d.ts +9 -0
  21. package/kernel/dist/helpers.js +23 -0
  22. package/kernel/dist/index.d.ts +8 -0
  23. package/kernel/dist/index.js +6 -0
  24. package/kernel/dist/preview-cache.d.ts +19 -0
  25. package/kernel/dist/preview-cache.js +29 -0
  26. package/kernel/dist/process.d.ts +12 -0
  27. package/kernel/dist/process.js +41 -0
  28. package/kernel/dist/tools.d.ts +67 -0
  29. package/kernel/dist/tools.js +20 -0
  30. package/kernel/dist/types.d.ts +26 -0
  31. package/kernel/dist/types.js +1 -0
  32. package/kernel/licenses/adler2-2.0.1-LICENSE-0BSD +12 -0
  33. package/kernel/licenses/adler2-2.0.1-LICENSE-APACHE +201 -0
  34. package/kernel/licenses/adler2-2.0.1-LICENSE-MIT +23 -0
  35. package/kernel/licenses/allocator-api2-0.2.21-LICENSE-APACHE +176 -0
  36. package/kernel/licenses/allocator-api2-0.2.21-LICENSE-MIT +23 -0
  37. package/kernel/licenses/autocfg-1.5.1-LICENSE-APACHE +201 -0
  38. package/kernel/licenses/autocfg-1.5.1-LICENSE-MIT +25 -0
  39. package/kernel/licenses/bitflags-1.3.2-LICENSE-APACHE +201 -0
  40. package/kernel/licenses/bitflags-1.3.2-LICENSE-MIT +25 -0
  41. package/kernel/licenses/block-buffer-0.10.4-LICENSE-APACHE +201 -0
  42. package/kernel/licenses/block-buffer-0.10.4-LICENSE-MIT +25 -0
  43. package/kernel/licenses/cfg-if-1.0.5-LICENSE-APACHE +201 -0
  44. package/kernel/licenses/cfg-if-1.0.5-LICENSE-MIT +25 -0
  45. package/kernel/licenses/cpufeatures-0.2.17-LICENSE-APACHE +201 -0
  46. package/kernel/licenses/cpufeatures-0.2.17-LICENSE-MIT +25 -0
  47. package/kernel/licenses/crc32fast-1.5.4-LICENSE-APACHE +202 -0
  48. package/kernel/licenses/crc32fast-1.5.4-LICENSE-MIT +21 -0
  49. package/kernel/licenses/crossbeam-deque-0.8.8-LICENSE-APACHE +201 -0
  50. package/kernel/licenses/crossbeam-deque-0.8.8-LICENSE-MIT +27 -0
  51. package/kernel/licenses/crossbeam-epoch-0.9.21-LICENSE-APACHE +201 -0
  52. package/kernel/licenses/crossbeam-epoch-0.9.21-LICENSE-MIT +27 -0
  53. package/kernel/licenses/crossbeam-utils-0.8.23-LICENSE-APACHE +201 -0
  54. package/kernel/licenses/crossbeam-utils-0.8.23-LICENSE-MIT +27 -0
  55. package/kernel/licenses/crypto-common-0.1.7-LICENSE-APACHE +201 -0
  56. package/kernel/licenses/crypto-common-0.1.7-LICENSE-MIT +25 -0
  57. package/kernel/licenses/dependencies.json +618 -0
  58. package/kernel/licenses/digest-0.10.7-LICENSE-APACHE +201 -0
  59. package/kernel/licenses/digest-0.10.7-LICENSE-MIT +25 -0
  60. package/kernel/licenses/dyn-clone-1.0.20-LICENSE-APACHE +176 -0
  61. package/kernel/licenses/dyn-clone-1.0.20-LICENSE-MIT +23 -0
  62. package/kernel/licenses/either-1.19.0-LICENSE-APACHE +201 -0
  63. package/kernel/licenses/either-1.19.0-LICENSE-MIT +25 -0
  64. package/kernel/licenses/equivalent-1.0.3-LICENSE-APACHE +201 -0
  65. package/kernel/licenses/equivalent-1.0.3-LICENSE-MIT +25 -0
  66. package/kernel/licenses/fdeflate-0.3.7-LICENSE-APACHE +177 -0
  67. package/kernel/licenses/fdeflate-0.3.7-LICENSE-MIT +25 -0
  68. package/kernel/licenses/flate2-1.1.10-LICENSE-APACHE +201 -0
  69. package/kernel/licenses/flate2-1.1.10-LICENSE-MIT +25 -0
  70. package/kernel/licenses/foldhash-0.2.0-LICENSE +19 -0
  71. package/kernel/licenses/generic-array-0.14.7-LICENSE +21 -0
  72. package/kernel/licenses/hashbrown-0.16.1-LICENSE-APACHE +201 -0
  73. package/kernel/licenses/hashbrown-0.16.1-LICENSE-MIT +25 -0
  74. package/kernel/licenses/itoa-1.0.18-LICENSE-APACHE +176 -0
  75. package/kernel/licenses/itoa-1.0.18-LICENSE-MIT +23 -0
  76. package/kernel/licenses/libc-0.2.191-LICENSE-APACHE +176 -0
  77. package/kernel/licenses/libc-0.2.191-LICENSE-MIT +25 -0
  78. package/kernel/licenses/memchr-2.8.3-COPYING +3 -0
  79. package/kernel/licenses/memchr-2.8.3-LICENSE-MIT +21 -0
  80. package/kernel/licenses/miniz_oxide-0.8.9-LICENSE +25 -0
  81. package/kernel/licenses/miniz_oxide-0.8.9-LICENSE-APACHE.md +177 -0
  82. package/kernel/licenses/miniz_oxide-0.8.9-LICENSE-MIT.md +24 -0
  83. package/kernel/licenses/miniz_oxide-0.8.9-LICENSE-ZLIB.md +14 -0
  84. package/kernel/licenses/miniz_oxide-0.9.1-LICENSE +25 -0
  85. package/kernel/licenses/miniz_oxide-0.9.1-LICENSE-APACHE.md +177 -0
  86. package/kernel/licenses/miniz_oxide-0.9.1-LICENSE-MIT.md +24 -0
  87. package/kernel/licenses/miniz_oxide-0.9.1-LICENSE-ZLIB.md +14 -0
  88. package/kernel/licenses/num-traits-0.2.19-LICENSE-APACHE +201 -0
  89. package/kernel/licenses/num-traits-0.2.19-LICENSE-MIT +25 -0
  90. package/kernel/licenses/png-0.17.16-LICENSE-APACHE +201 -0
  91. package/kernel/licenses/png-0.17.16-LICENSE-MIT +25 -0
  92. package/kernel/licenses/proc-macro2-1.0.107-LICENSE-APACHE +176 -0
  93. package/kernel/licenses/proc-macro2-1.0.107-LICENSE-MIT +23 -0
  94. package/kernel/licenses/quote-1.0.47-LICENSE-APACHE +176 -0
  95. package/kernel/licenses/quote-1.0.47-LICENSE-MIT +23 -0
  96. package/kernel/licenses/rayon-1.12.0-LICENSE-APACHE +201 -0
  97. package/kernel/licenses/rayon-1.12.0-LICENSE-MIT +25 -0
  98. package/kernel/licenses/rayon-core-1.13.0-LICENSE-APACHE +201 -0
  99. package/kernel/licenses/rayon-core-1.13.0-LICENSE-MIT +25 -0
  100. package/kernel/licenses/ref-cast-1.0.27-LICENSE-APACHE +176 -0
  101. package/kernel/licenses/ref-cast-1.0.27-LICENSE-MIT +23 -0
  102. package/kernel/licenses/ref-cast-impl-1.0.27-LICENSE-APACHE +176 -0
  103. package/kernel/licenses/ref-cast-impl-1.0.27-LICENSE-MIT +23 -0
  104. package/kernel/licenses/robust-1.2.0-LICENSE-APACHE +201 -0
  105. package/kernel/licenses/robust-1.2.0-LICENSE-MIT +26 -0
  106. package/kernel/licenses/schemars-1.2.3-LICENSE +21 -0
  107. package/kernel/licenses/schemars_derive-1.2.3-LICENSE +21 -0
  108. package/kernel/licenses/serde-1.0.229-LICENSE-APACHE +176 -0
  109. package/kernel/licenses/serde-1.0.229-LICENSE-MIT +23 -0
  110. package/kernel/licenses/serde_core-1.0.229-LICENSE-APACHE +176 -0
  111. package/kernel/licenses/serde_core-1.0.229-LICENSE-MIT +23 -0
  112. package/kernel/licenses/serde_derive-1.0.229-LICENSE-APACHE +176 -0
  113. package/kernel/licenses/serde_derive-1.0.229-LICENSE-MIT +23 -0
  114. package/kernel/licenses/serde_derive_internals-0.30.0-LICENSE-APACHE +176 -0
  115. package/kernel/licenses/serde_derive_internals-0.30.0-LICENSE-MIT +23 -0
  116. package/kernel/licenses/serde_json-1.0.154-LICENSE-APACHE +176 -0
  117. package/kernel/licenses/serde_json-1.0.154-LICENSE-MIT +23 -0
  118. package/kernel/licenses/sha2-0.10.9-LICENSE-APACHE +201 -0
  119. package/kernel/licenses/sha2-0.10.9-LICENSE-MIT +27 -0
  120. package/kernel/licenses/simd-adler32-0.3.10-LICENSE.md +21 -0
  121. package/kernel/licenses/smallvec-1.16.4-LICENSE-APACHE +201 -0
  122. package/kernel/licenses/smallvec-1.16.4-LICENSE-MIT +25 -0
  123. package/kernel/licenses/solidcore-1.0.1-LICENSE +203 -0
  124. package/kernel/licenses/solidcore-1.0.1-NOTICE +30 -0
  125. package/kernel/licenses/solidcore-ATTRIBUTION.md +92 -0
  126. package/kernel/licenses/solidcore-LICENSE +203 -0
  127. package/kernel/licenses/solidcore-NOTICE +30 -0
  128. package/kernel/licenses/solidcore-convert-0.1.0-ATTRIBUTION.md +92 -0
  129. package/kernel/licenses/solidcore-convert-0.1.0-LICENSE +203 -0
  130. package/kernel/licenses/solidcore-convert-0.1.0-NOTICE +30 -0
  131. package/kernel/licenses/solidcore-record-0.1.0-ATTRIBUTION.md +92 -0
  132. package/kernel/licenses/solidcore-record-0.1.0-LICENSE +203 -0
  133. package/kernel/licenses/solidcore-record-0.1.0-NOTICE +30 -0
  134. package/kernel/licenses/solidcore-tess-0.1.0-ATTRIBUTION.md +92 -0
  135. package/kernel/licenses/solidcore-tess-0.1.0-LICENSE +203 -0
  136. package/kernel/licenses/solidcore-tess-0.1.0-NOTICE +30 -0
  137. package/kernel/licenses/spade-2.15.1-LICENSE-APACHE +202 -0
  138. package/kernel/licenses/spade-2.15.1-LICENSE-MIT +25 -0
  139. package/kernel/licenses/step-brep-0.1.0-ATTRIBUTION.md +92 -0
  140. package/kernel/licenses/step-brep-0.1.0-LICENSE +203 -0
  141. package/kernel/licenses/step-brep-0.1.0-NOTICE +30 -0
  142. package/kernel/licenses/step-export-0.1.0-ATTRIBUTION.md +92 -0
  143. package/kernel/licenses/step-export-0.1.0-LICENSE +203 -0
  144. package/kernel/licenses/step-export-0.1.0-NOTICE +30 -0
  145. package/kernel/licenses/step-import-0.1.0-ATTRIBUTION.md +92 -0
  146. package/kernel/licenses/step-import-0.1.0-LICENSE +203 -0
  147. package/kernel/licenses/step-import-0.1.0-NOTICE +30 -0
  148. package/kernel/licenses/syn-3.0.9-LICENSE-APACHE +176 -0
  149. package/kernel/licenses/syn-3.0.9-LICENSE-MIT +23 -0
  150. package/kernel/licenses/thiserror-2.0.21-LICENSE-APACHE +176 -0
  151. package/kernel/licenses/thiserror-2.0.21-LICENSE-MIT +23 -0
  152. package/kernel/licenses/thiserror-impl-2.0.21-LICENSE-APACHE +176 -0
  153. package/kernel/licenses/thiserror-impl-2.0.21-LICENSE-MIT +23 -0
  154. package/kernel/licenses/typenum-1.20.1-LICENSE +1 -0
  155. package/kernel/licenses/typenum-1.20.1-LICENSE-APACHE +201 -0
  156. package/kernel/licenses/typenum-1.20.1-LICENSE-MIT +21 -0
  157. package/kernel/licenses/unicode-ident-1.0.27-LICENSE-APACHE +176 -0
  158. package/kernel/licenses/unicode-ident-1.0.27-LICENSE-MIT +23 -0
  159. package/kernel/licenses/unicode-ident-1.0.27-LICENSE-UNICODE +39 -0
  160. package/kernel/licenses/version_check-0.9.5-LICENSE-APACHE +201 -0
  161. package/kernel/licenses/version_check-0.9.5-LICENSE-MIT +19 -0
  162. package/kernel/licenses/zlib-rs-0.6.8-LICENSE +19 -0
  163. package/kernel/licenses/zmij-1.0.23-LICENSE-MIT +23 -0
  164. package/kernel/native/darwin-arm64/agent-cad +4 -0
  165. package/kernel/native/darwin-arm64/manifest.json +6 -0
  166. package/kernel/native/linux-arm64/agent-cad +4 -0
  167. package/kernel/native/linux-arm64/manifest.json +6 -0
  168. package/kernel/native/linux-x64/agent-cad +4 -0
  169. package/kernel/native/linux-x64/manifest.json +6 -0
  170. package/kernel/schemas/model.schema.json +4080 -0
  171. package/package.json +54 -4
  172. package/solidworks/managed/Colocad.SolidWorks.deps.json +23 -0
  173. package/solidworks/managed/Colocad.SolidWorks.dll +0 -0
  174. package/solidworks/managed/Colocad.SolidWorks.runtimeconfig.json +13 -0
  175. package/src/build.mjs +69 -0
  176. package/src/index.d.mts +67 -0
  177. package/src/index.mjs +4 -0
  178. package/src/solidworks.mjs +65 -0
  179. 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,54 @@
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
+ Local parametric CAD for agents. A TypeScript-compatible API compiles ordered sketch extrusions, cuts, constant-radius fillets and linear feature patterns. A Rust B-rep kernel executes the graph inside the calling agent's sandbox. Node.js 22+.
4
+
5
+ **Alpha status.** Linux supports instruction-to-STEP, mesh previews, parameter edits and geometry verification. Direct editable SLDPRT generation on Linux is under development. A separate local Windows author uses the native SOLIDWORKS FeatureManager. It compiles against the 2024 interop API and awaits a licensed SOLIDWORKS runtime test. The Linux CLI returns `NATIVE_AUTHOR_UNAVAILABLE` for the native command.
6
+
7
+ ## Run the examples
8
+
9
+ ```sh
10
+ npm install @coloopx/colocad@alpha
11
+ npx colocad build node_modules/@coloopx/colocad/examples/manifold.json ./manifold --preview
12
+ npx colocad build node_modules/@coloopx/colocad/examples/sensor-rail.json ./rail
13
+ ```
14
+
15
+ 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.
16
+
17
+ 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.
18
+
19
+ ```js
20
+ import { readFile } from 'node:fs/promises';
21
+ import { build } from '@coloopx/colocad';
22
+
23
+ const tree = JSON.parse(await readFile('./node_modules/@coloopx/colocad/examples/manifold.json', 'utf8'));
24
+ await build(tree, './original');
25
+ tree.parameters.instances = 3;
26
+ const edited = await build(tree, './edited');
27
+ console.log(edited.geometry.volume_mm3);
28
+ ```
29
+
30
+ 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.
31
+
32
+ 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.
33
+
34
+ ## Native SOLIDWORKS author (experimental)
35
+
36
+ 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.
37
+
38
+ ```powershell
39
+ colocad solidworks .\manifold\part\native-job.json .\manifold.SLDPRT
40
+ ```
41
+
42
+ 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.
43
+
44
+ ## Build and verify from source
45
+
46
+ ```sh
47
+ npm run build:kernel
48
+ npm test
49
+ node bin/colocad.mjs build examples/manifold.json ./out/manifold --preview
50
+ ```
51
+
52
+ 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.
53
+
54
+ 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,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
+ }>;
@@ -0,0 +1,103 @@
1
+ import { open, readFile, writeFile, link, unlink } from 'node:fs/promises';
2
+ import { randomUUID, createHash } from 'node:crypto';
3
+ import { dirname, basename, extname, join } from 'node:path';
4
+ import { attachStep } from './assets.js';
5
+ const limit = 32 * 1024 * 1024;
6
+ const marker = '/* AGENT_CAD_IR_1 ';
7
+ const hash = (s) => createHash('sha256').update(s).digest('hex');
8
+ function requireData(r) { if (!r.ok)
9
+ throw Object.assign(Error(r.error.message), { code: r.error.code }); return r.data; }
10
+ const unsupported = (path) => Object.assign(Error('No local CAD file codec for ' + extname(path)), { code: 'UNSUPPORTED_FILE_FORMAT' });
11
+ async function bounded(path) {
12
+ const fd = await open(path, 'r');
13
+ try {
14
+ const s = await fd.stat();
15
+ if (!s.isFile() || s.size > limit)
16
+ throw Error('CAD input must be a regular file up to 32 MiB');
17
+ const bytes = await fd.readFile();
18
+ if (bytes.length > limit)
19
+ throw Error('CAD file grew beyond its budget');
20
+ return bytes;
21
+ }
22
+ finally {
23
+ await fd.close();
24
+ }
25
+ }
26
+ /** Paths belong to the Harness in the current sandbox. Foreign STEP geometry is imported as an asset. */
27
+ export async function readModelFile(cad, path) {
28
+ const ext = extname(path).toLowerCase();
29
+ if (!['.json', '.step', '.stp'].includes(ext))
30
+ throw unsupported(path);
31
+ const raw = (await bounded(path)).toString('utf8');
32
+ let model;
33
+ if (ext === '.json') {
34
+ model = JSON.parse(raw);
35
+ }
36
+ else {
37
+ if (!/^\s*ISO-10303-21;/i.test(raw))
38
+ throw Error('invalid STEP exchange header');
39
+ const start = raw.indexOf(marker);
40
+ if (start < 0) {
41
+ const id = 'source_part';
42
+ const seed = attachStep({ version: 1, units: 'mm', parameters: {}, features: [], output: '' }, id, raw);
43
+ const inspected = requireData(await cad.inspectStep(seed, id));
44
+ model = { ...inspected.model_template, assets: seed.assets };
45
+ }
46
+ else {
47
+ const end = raw.indexOf(' */\n', start);
48
+ if (end < 0 || raw.indexOf(marker, start + marker.length) >= 0)
49
+ throw Error('invalid embedded model record');
50
+ const fields = raw.slice(start + marker.length, end).split(' ');
51
+ if (fields.length !== 3)
52
+ throw Error('invalid embedded model fields');
53
+ const [stepHash, sourceHash, encoded] = fields;
54
+ const step = raw.slice(0, start) + raw.slice(end + 4);
55
+ const source = Buffer.from(encoded, 'base64');
56
+ if (hash(step) !== stepHash || hash(source) !== sourceHash || source.toString('base64') !== encoded)
57
+ throw Error('embedded model or STEP digest mismatch');
58
+ model = JSON.parse(source.toString('utf8'));
59
+ }
60
+ }
61
+ requireData(await cad.validate(model));
62
+ return model;
63
+ }
64
+ async function publish(path, bytes) {
65
+ const temp = join(dirname(path), '.' + basename(path) + '.' + randomUUID() + '.tmp');
66
+ try {
67
+ await writeFile(temp, bytes, { flag: 'wx', mode: 0o600 });
68
+ await link(temp, path);
69
+ }
70
+ finally {
71
+ await unlink(temp).catch(e => { if (e.code !== 'ENOENT')
72
+ throw e; });
73
+ }
74
+ }
75
+ /** Export a new file. A STEP with embedModel=true can be reopened and edited from that single file. */
76
+ export async function writeModelFile(cad, model, path, options = {}) {
77
+ const ext = extname(path).toLowerCase();
78
+ const names = { '.json': 'model.json', '.step': 'model.step', '.stp': 'model.step', '.glb': 'model.glb', '.stl': 'model.stl', '.png': 'preview.png' };
79
+ if (!Object.hasOwn(names, ext))
80
+ throw unsupported(path);
81
+ const preview = ['.png', '.stl', '.glb'].includes(ext);
82
+ const receipt = requireData(await cad.build(preview ? { ...model, preview: model.preview ?? {} } : model));
83
+ let bytes = await readFile(join(String(receipt.artifact_directory), names[ext]));
84
+ if (options.embedModel && ['.step', '.stp'].includes(ext)) {
85
+ const step = bytes.toString('utf8'), source = Buffer.from(JSON.stringify(model), 'utf8');
86
+ const first = step.indexOf('\n') + 1;
87
+ if (!first)
88
+ throw Error('invalid STEP output header');
89
+ const comment = marker + hash(bytes) + ' ' + hash(source) + ' ' + source.toString('base64') + ' */\n';
90
+ bytes = Buffer.from(step.slice(0, first) + comment + step.slice(first));
91
+ }
92
+ if (bytes.length > limit)
93
+ throw Error('file exceeds 32 MiB');
94
+ await publish(path, bytes);
95
+ return { path, bytes: bytes.length, sha256: hash(bytes), model_hash: String(receipt.model_hash) };
96
+ }
97
+ export async function editModelFile(cad, source, parameters, destination) {
98
+ const model = await readModelFile(cad, source);
99
+ for (const [key, value] of Object.entries(parameters))
100
+ if (!Object.hasOwn(model.parameters, key) || !Number.isFinite(value))
101
+ throw Error('unknown or nonfinite parameter: ' + key);
102
+ return writeModelFile(cad, { ...model, parameters: { ...model.parameters, ...parameters } }, destination, { embedModel: true });
103
+ }