@coloopx/colocad 0.1.0-alpha.6 → 0.1.0-alpha.7

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 (46) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +9 -3
  3. package/README.zh-CN.md +8 -3
  4. package/bin/colocad.mjs +17 -9
  5. package/docs/README.md +7 -2
  6. package/docs/README.zh-CN.md +9 -2
  7. package/docs/agent-modeling-handbook.md +1 -1
  8. package/docs/agent-modeling-handbook.zh-CN.md +2 -2
  9. package/docs/api.md +9 -6
  10. package/docs/engineering-queries.md +122 -0
  11. package/docs/engineering-queries.zh-CN.md +74 -0
  12. package/docs/getting-started.md +1 -1
  13. package/docs/integrations/claude-code.md +1 -1
  14. package/docs/integrations/codex.md +1 -1
  15. package/docs/integrations/pi.md +17 -4
  16. package/docs/integrations/verification.md +7 -1
  17. package/examples/integrations/README.md +11 -2
  18. package/examples/integrations/compact-tools.mjs +1 -1
  19. package/kernel/dist/client.d.ts +5 -2
  20. package/kernel/dist/client.js +35 -7
  21. package/kernel/dist/generated.d.ts +297 -4
  22. package/kernel/dist/process.d.ts +1 -1
  23. package/kernel/dist/process.js +3 -3
  24. package/kernel/dist/query-generated.d.ts +181 -0
  25. package/kernel/dist/query-generated.js +1 -0
  26. package/kernel/dist/tools.d.ts +35 -0
  27. package/kernel/dist/tools.js +11 -2
  28. package/kernel/dist/types.d.ts +9 -0
  29. package/kernel/native/darwin-arm64/agent-cad +2 -2
  30. package/kernel/native/darwin-arm64/manifest.json +2 -2
  31. package/kernel/native/linux-arm64/agent-cad +2 -2
  32. package/kernel/native/linux-arm64/manifest.json +2 -2
  33. package/kernel/native/linux-x64/agent-cad +2 -2
  34. package/kernel/native/linux-x64/manifest.json +2 -2
  35. package/kernel/release.json +4 -4
  36. package/kernel/schemas/model.schema.json +1752 -135
  37. package/kernel/schemas/query.schema.json +1150 -0
  38. package/package.json +5 -2
  39. package/skills/colocad/references/tool-contracts.md +14 -2
  40. package/src/build.mjs +3 -2
  41. package/src/index.d.mts +2 -1
  42. package/src/session.d.mts +5 -3
  43. package/src/session.mjs +26 -10
  44. package/viewer/dist/index.js +179 -179
  45. package/viewer/dist/standalone.js +179 -179
  46. package/viewer/index.d.ts +2 -1
@@ -4,15 +4,23 @@ The adapter is tested with `@earendil-works/pi-agent-core@1.5.0` and `@earendil-
4
4
 
5
5
  ## Pi agent core: register local tools
6
6
 
7
- Clone the example project and install its lockfile:
7
+ Clone the repository and build the matching development native/SDK before running the current query-enabled adapter tests (Node.js 22+ and Rust required):
8
8
 
9
9
  ```sh
10
10
  git clone https://github.com/Coloopx/colocad.git
11
- cd colocad/examples/integrations
11
+ cd colocad
12
+ node scripts/vendor.mjs
13
+ cargo build --locked --release -p agent-cad
14
+ export AGENT_CAD_BINARY="$PWD/target/release/agent-cad"
15
+ npm ci --prefix kernel --ignore-scripts
16
+ npm run build --prefix kernel
17
+ cd examples/integrations
12
18
  npm ci --ignore-scripts
13
19
  npm test
14
20
  ```
15
21
 
22
+ If `CARGO_TARGET_DIR` is configured, use its release executable in `AGENT_CAD_BINARY`. Published alpha.6 natives do not expose the new query contract. The separate legacy `sdk.mjs` example still pins alpha.3.
23
+
16
24
  [pi-tools.mjs](../../examples/integrations/pi-tools.mjs) adapts colocad's JSON Schemas and receipts to Pi `AgentTool`s. [pi-core.mjs](../../examples/integrations/pi-core.mjs) constructs an agent with these tools. Your harness supplies its existing model, stream function and authentication:
17
25
 
18
26
  ```js
@@ -45,7 +53,7 @@ From the example project after `npm ci`:
45
53
  ./node_modules/.bin/pi --extension ./pi-extension.mjs
46
54
  ```
47
55
 
48
- The extension registers five `cad_*` tools. Output defaults to `./cad-output`; set `COLOCAD_OUTPUT_DIR` in the shell launching Pi to choose a trusted absolute destination. Start it from the intended project directory and restart/rebind when changing projects. Use Pi's existing model/auth configuration.
56
+ The extension registers five core `cad_*` tools plus `cad_query` when the native capabilities advertise the exact query API. Output defaults to `./cad-output`; set `COLOCAD_OUTPUT_DIR` in the shell launching Pi to choose a trusted absolute destination. Start it from the intended project directory and restart/rebind when changing projects. Use Pi's existing model/auth configuration.
49
57
 
50
58
  For the modeling workflow as well, load the bundled skill:
51
59
 
@@ -68,6 +76,11 @@ test ! -e .agents/skills/colocad && \
68
76
 
69
77
  Start Pi in that project and invoke `/skill:colocad`. Keep the complete folder: its instructions reference scripts, assets and supporting guides. Review the project skill under Pi's normal project trust flow. No global install or permissions bypass is required.
70
78
 
71
- The example tests execute the actual Pi core loop with deterministic model responses, the actual extension loader, and the published Rust binary. They do not call a live model provider. See [verification scope](verification.md).
79
+ The example tests execute the actual Pi core loop with deterministic model responses, the actual extension loader, and the configured Rust binary. These six deterministic tests do not call a live model provider. Separate [G3 acceptance](../../specs/experiments/0005/README.md) records actual Pi inference, local tools, session history and native CAD inside Linux arm64 1 vCPU / 512 MiB, including a text-built plate and a sourced 82-solid product edit. See [verification scope](verification.md).
72
80
 
73
81
  References checked 2026-11-07: [Pi core](https://github.com/earendil-works/pi/tree/main/packages/agent), [extensions](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md), [skills](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md). The installed 1.5.0 declarations and CLI help were also checked.
82
+
83
+
84
+ For Pi AI 1.5, provider-specific streaming comes from `@earendil-works/pi-ai/api/openai-completions`, which exports `streamSimple`; it is not exported by the package root. Supply this through the harness's `streamFn` with its configured endpoint/model/auth. The [live acceptance runner](../../specs/experiments/0005/sandbox/live.mjs) is a complete example with an external read-only credential file, bounded turns/time, persisted tool/inference traces and resource accounting. Keep credentials out of model prompts and traces.
85
+
86
+ Build/edit feedback retains the query revision and full receipts on disk. The adapter exposes structured query results and explicit degradation. The source adapter imports this checkout's SDK; its published alpha.3 dependency remains only for the separate legacy SDK compatibility example. For new query work compile the native and SDK from the same checkout as explained in the [query guide](../engineering-queries.md).
@@ -1,6 +1,6 @@
1
1
  # Integration verification
2
2
 
3
- Verified on **2026-11-07**, Node.js **22.23.3**, **macOS arm64**, using the public npm package **@coloopx/colocad@0.1.0-alpha.3** and its bundled Rust binary. Pi core, Pi AI and Pi coding agent are pinned to **1.5.0** in the example lockfile.
3
+ Historical baseline verified on **2026-11-07**, Node.js **22.23.3**, **macOS arm64**, using the public npm package **@coloopx/colocad@0.1.0-alpha.3** and its bundled Rust binary. Pi core, Pi AI and Pi coding agent are pinned to **1.5.0** in the example lockfile.
4
4
 
5
5
  | Check | Result | What it establishes |
6
6
  | --- | --- | --- |
@@ -28,3 +28,9 @@ The five integration tests run native CAD operations and actual Pi library code.
28
28
  Codex skill paths/invocation and Claude Code skill paths/invocation were checked against their official documentation. The bundled helper was run from both `.agents/skills/colocad` and `.claude/skills/colocad`. No Claude Code live session was run, and this test run did not evaluate a live Codex model reconstructing a drawing. The Pi live-provider schema negotiation remains dependent on the provider you configure.
29
29
 
30
30
  This verification adds no new performance claims. Cross-platform npm release checks are recorded separately in [release-alpha.3.json](../evidence/release-alpha.3.json); the new adapter regression itself was run on macOS arm64. Native SOLIDWORKS acceptance remains subject to the [existing limitations](../validation.md).
31
+
32
+ ## Engineering-query and release verification (2026-11-09)
33
+
34
+ Current source passes six deterministic Pi/integration tests, including capability-gated `cad_query`, revision-aware feedback and recorded errors. Two additional [G3 live Pi tasks](../../specs/experiments/0005/README.md) use real remote inference while the agent/harness/SDK/native execute in one limited Linux sandbox. They cover a text-built plate and an edit/query of a seeded 82-solid product; they do not measure unseen-image reconstruction.
35
+
36
+ The [alpha.7 archive record](../evidence/release-alpha.7.json) adds fresh-package SDK/CLI/query/foreign-replacement checks on macOS arm64 and Linux arm64/x64, independent OCCT readback and offline browser verification. Historical alpha.3 verification above remains scoped to that release.
@@ -1,27 +1,36 @@
1
1
  # Runnable integration examples
2
2
 
3
- This example project installs published `@coloopx/colocad@0.1.0-alpha.3`. It does not depend on a locally compiled kernel. Node.js 22+ and one of the package's supported platforms are required.
3
+ The standalone `sdk.mjs` keeps published `@coloopx/colocad@0.1.0-alpha.3` as a compatibility example. The Pi/session adapters import this checkout's SDK; their current query tests require the matching development native. Node.js 22+ is required, plus Rust to build the development executable.
4
4
 
5
5
  From the repository root:
6
6
 
7
7
  ```sh
8
+ node scripts/vendor.mjs
9
+ cargo build --locked --release -p agent-cad
10
+ export AGENT_CAD_BINARY="$PWD/target/release/agent-cad"
11
+ npm ci --prefix kernel --ignore-scripts
12
+ npm run build --prefix kernel
8
13
  npm ci --prefix examples/integrations --ignore-scripts
9
14
  npm test --prefix examples/integrations
10
15
  node examples/integrations/sdk.mjs ./out/sdk-example
11
16
  ```
12
17
 
18
+ If you set `CARGO_TARGET_DIR`, point `AGENT_CAD_BINARY` at that directory's release executable instead. Unset `AGENT_CAD_BINARY` to run only the legacy `sdk.mjs` against its bundled alpha.3 native; that does not test the new query API.
19
+
13
20
  `sdk.mjs` validates a four-hole plate, renders it, changes the camera using its cached mesh, changes the bore diameter and saves the current source. It prints the artifact paths. Its output root can be reused because the SDK creates new revision subdirectories.
14
21
 
15
22
  | File | Purpose |
16
23
  | --- | --- |
17
24
  | [sdk.mjs](sdk.mjs) | Actual SDK modeling/edit/observation cycle |
18
- | [pi-tools.mjs](pi-tools.mjs) | Five Pi tools, schema preservation, error mapping and PNG attachment |
25
+ | [pi-tools.mjs](pi-tools.mjs) | Five core Pi tools plus capability-gated `cad_query`, schema preservation, revision-aware feedback, error mapping and PNG attachment |
19
26
  | [pi-core.mjs](pi-core.mjs) | Construct a Pi core agent with a caller-supplied model and stream function |
20
27
  | [pi-extension.mjs](pi-extension.mjs) | Register the same tools in Pi coding agent |
21
28
  | [integration.test.mjs](integration.test.mjs) | Real native calls and Pi loop/extension/skill discovery regression tests |
22
29
 
23
30
  The test model stream is scripted; no LLM provider or credentials are needed. The test asserts a failed edit reaches the agent as an error and the subsequent corrected call exports STEP. It measures integration correctness, not model intelligence or drawing reconstruction success.
24
31
 
32
+ Separate [G3 live acceptance](../../specs/experiments/0005/README.md) runs Pi inference with local tools, harness and native in the same 1 vCPU / 512 MiB sandbox. It includes a text-built plate and a seeded 82-solid product edit, with actual tool traces and independent STEP readback. These are bounded tasks, not a drawing-reconstruction success-rate study.
33
+
25
34
  Use the [Pi guide](../../docs/integrations/pi.md) to connect real inference. [Codex](../../docs/integrations/codex.md) and [Claude Code](../../docs/integrations/claude-code.md) use the bundled skill and local CLI. These example files live in GitHub and are not part of the existing alpha.3 tarball.
26
35
 
27
36
  ## Record history in the source checkout
@@ -10,7 +10,7 @@ export function compactReceipt(receipt){
10
10
  .map(([name,sha256])=>[name,{path:join(d.artifact_directory,name),sha256}]));
11
11
  return {ok:true,...(receipt.session_step?{session_step:receipt.session_step}:{}),data:{
12
12
  artifact_directory:d.artifact_directory,source_artifact_directory:d.source_artifact_directory,
13
- model_hash:d.model_hash,source_hash:d.source_hash,geometry:structuredClone(d.geometry),
13
+ model_hash:d.model_hash,source_hash:d.source_hash,query_revision_id:d.query_revision_id,execution_policy:d.execution_policy,geometry:structuredClone(d.geometry),
14
14
  timing_ms:structuredClone(d.timing_ms),validation:structuredClone(d.validation),artifacts,
15
15
  feature_summary:{count:features.length,reused:features.filter(f=>f.cache_hit).length,
16
16
  slowest:[...features].sort((a,b)=>(b.elapsed_ms??0)-(a.elapsed_ms??0)).slice(0,3).map(f=>({id:f.id,elapsed_ms:f.elapsed_ms,cache_hit:f.cache_hit})),
@@ -1,21 +1,24 @@
1
- import type { Config, Model, Receipt, PreviewOptions, Sketch } from './types.js';
1
+ import type { Config, Model, Receipt, PreviewOptions, Sketch, BuildOptions, QueryRequest } from './types.js';
2
2
  export type * from './types.js';
3
3
  export { attachStep } from './assets.js';
4
4
  /** Local CAD API for the Harness and Agent sharing this sandbox. */
5
5
  export declare class CadClient {
6
6
  private readonly config;
7
7
  private previousRevision?;
8
+ private previousQueryable;
8
9
  private readonly previewCache;
9
10
  constructor(config: Config);
10
11
  capabilities(): Promise<Receipt>;
11
12
  schema(): Promise<Receipt>;
13
+ querySchema(): Promise<Receipt>;
14
+ query(directory: string, request: QueryRequest): Promise<Receipt>;
12
15
  validate(model: Model): Promise<Receipt>;
13
16
  solveSketch(sketch: Sketch, parameters?: Record<string, number>): Promise<Receipt>;
14
17
  inspectStep(model: Model, asset: string): Promise<Receipt>;
15
18
  preview(model: Model, options?: Partial<PreviewOptions>): Promise<Receipt>;
16
19
  /** Resume display from a trusted host artifact path, including in a new SDK process. */
17
20
  observeArtifact(directory: string, options?: Partial<PreviewOptions>): Promise<Receipt>;
18
- build(model: Model, previousRevision?: string | undefined): Promise<Receipt>;
21
+ build(model: Model, optionsOrRevision?: BuildOptions | string): Promise<Receipt>;
19
22
  edit(model: Model, parameters: Record<string, number>): Promise<Receipt>;
20
23
  inspect(artifactDirectory: string): Promise<Record<string, unknown>>;
21
24
  private invoke;
@@ -1,5 +1,5 @@
1
- import { readFile } from 'node:fs/promises';
2
- import { join } from 'node:path';
1
+ import { readFile, realpath } from 'node:fs/promises';
2
+ import { join, relative, isAbsolute, sep } from 'node:path';
3
3
  import { artifactJob } from './artifacts.js';
4
4
  import { resolveBinary } from './binary.js';
5
5
  import { execute, receipt, error } from './process.js';
@@ -9,6 +9,7 @@ export { attachStep } from './assets.js';
9
9
  export class CadClient {
10
10
  config;
11
11
  previousRevision;
12
+ previousQueryable = false;
12
13
  previewCache = new Map();
13
14
  constructor(config) {
14
15
  this.config = config;
@@ -20,6 +21,26 @@ export class CadClient {
20
21
  }
21
22
  async capabilities() { return this.invoke(['capabilities']); }
22
23
  async schema() { return this.invoke(['schema']); }
24
+ async querySchema() { return this.invoke(['query-schema']); }
25
+ async query(directory, request) {
26
+ try {
27
+ const actual = await realpath(directory);
28
+ let allowed = false;
29
+ for (const root of this.config.queryRoots ?? [this.config.outputRoot]) {
30
+ const base = await realpath(root), path = relative(base, actual);
31
+ if (path === '' || (!isAbsolute(path) && path !== '..' && !path.startsWith('..' + sep)))
32
+ allowed = true;
33
+ }
34
+ if (!allowed)
35
+ return error('QUERY_ARTIFACT_OUTSIDE_ROOT', 'Artifact is outside the host-configured query roots');
36
+ if (Buffer.byteLength(JSON.stringify(request)) > 2 * 1024 * 1024)
37
+ return error('QUERY_LIMIT', 'Query request exceeds 2 MiB');
38
+ return this.invoke(['query', '--snapshot', actual], request);
39
+ }
40
+ catch (cause) {
41
+ return error('QUERY_ARTIFACT_READ_FAILED', String(cause));
42
+ }
43
+ }
23
44
  async validate(model) { return this.invoke(['validate'], model); }
24
45
  async solveSketch(sketch, parameters = {}) {
25
46
  return this.invoke(['solve-sketch'], { sketch, parameters });
@@ -60,11 +81,18 @@ export class CadClient {
60
81
  return error(cause instanceof CacheError ? cause.code : 'PREVIEW_CACHE_READ_FAILED', String(cause));
61
82
  }
62
83
  }
63
- async build(model, previousRevision = this.previousRevision) {
84
+ async build(model, optionsOrRevision) {
85
+ const options = typeof optionsOrRevision === 'string' ? { previousRevision: optionsOrRevision } : optionsOrRevision ?? {};
86
+ if (options.queryable === false && (model.datums?.length || model.interfaces?.length))
87
+ return error('QUERY_SNAPSHOT_REQUIRED', 'Datum/interface declarations require queryable artifacts');
88
+ const queryable = options.queryable ?? !!(model.datums?.length || model.interfaces?.length);
89
+ const previousRevision = options.previousRevision ?? this.previousRevision;
64
90
  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)
91
+ const result = await artifactJob(this.config, 'job-', (_job, destination) => this.invoke(['build', '--out', destination, ...checkpoints, ...(queryable ? ['--queryable'] : [])], model));
92
+ if (result.ok) {
67
93
  this.previousRevision = result.data.artifact_directory;
94
+ this.previousQueryable = queryable;
95
+ }
68
96
  if (result.ok && model.preview && result.data.artifact_sha256?.['preview.mesh.json']) {
69
97
  this.previewCache.set(previewKey(model), result.data.artifact_directory);
70
98
  if (this.previewCache.size > 16)
@@ -79,7 +107,7 @@ export class CadClient {
79
107
  if (!Number.isFinite(value))
80
108
  return error('INVALID_PARAMETER', key);
81
109
  }
82
- return this.build({ ...structuredClone(model), parameters: { ...model.parameters, ...parameters } });
110
+ return this.build({ ...structuredClone(model), parameters: { ...model.parameters, ...parameters } }, { queryable: this.previousQueryable });
83
111
  }
84
112
  async inspect(artifactDirectory) {
85
113
  return JSON.parse(await readFile(join(artifactDirectory, 'report.json'), 'utf8'));
@@ -90,7 +118,7 @@ export class CadClient {
90
118
  return error('RESOURCE_LIMIT', 'input exceeds 32 MiB');
91
119
  try {
92
120
  const binary = resolveBinary(this.config.binary ?? this.config.runner?.binary);
93
- return receipt(await execute(binary, args, input, this.config.wallMs ?? 30_000));
121
+ return receipt(await execute(binary, args, input, this.config.wallMs ?? 30_000, args[0] === 'query' ? 8 * 1024 * 1024 : 2 * 1024 * 1024));
94
122
  }
95
123
  catch (cause) {
96
124
  return error('LOCAL_EXECUTION_FAILED', String(cause));