@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/src/lib/cad/openscad.js

@@ -0,0 +1,198 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { runProcess } from '../../security/process.js';
+import { discoverOpenScad, openScadStatus } from './discovery.js';
+import { probeDockerServiceHealth, executeOpenScadDocker } from './docker-executor.js';
+
+export const FORBIDDEN_OPENSCAD_PATTERNS = [
+  /\bimport\s*\(/i,
+  /\binclude\s*<(?!\s*MCAD)/i,
+  /\buse\s*<(?!\s*MCAD)/i,
+  /\bexec\s*\(/i,
+  /\bsystem\s*\(/i,
+  /\bchild_process\b/i,
+  /\bread_file\b/i,
+  /\bwrite_file\b/i,
+  /\bprocess\.env\b/i,
+  /\.\.\//,
+];
+
+export function validateOpenScadSource(source) {
+  if (typeof source !== 'string' || !source.trim()) {
+    throw new Error('OpenSCAD source code is required');
+  }
+
+  for (const pat of FORBIDDEN_OPENSCAD_PATTERNS) {
+    if (pat.test(source)) {
+      throw new Error(`Security Violation: forbidden pattern detected (${pat.toString()})`);
+    }
+  }
+}
+
+function resolveMimeType(format) {
+  switch (format.toLowerCase()) {
+    case 'stl':
+      return 'model/stl';
+    case 'dxf':
+      return 'image/vnd.dxf';
+    case 'svg':
+      return 'image/svg+xml';
+    case '3mf':
+      return 'model/3mf';
+    case 'obj':
+      return 'model/obj';
+    default:
+      return 'text/plain';
+  }
+}
+
+/**
+ * Compiles an OpenSCAD script using the native OpenSCAD binary when available,
+ * with deterministic sandboxing and parameter injection.
+ */
+export async function openScadCompile({
+  source,
+  outputFormat = 'stl',
+  parameters = {},
+  filename,
+  openscadBin,
+  timeoutMs = 25000,
+  cwd = process.cwd(),
+  runProcessImpl = runProcess,
+} = {}) {
+  validateOpenScadSource(source);
+
+  const format = outputFormat.toLowerCase().replace(/^\./, '');
+  const outFilename = filename || `model.${format}`;
+  const mimeType = resolveMimeType(format);
+  const started = Date.now();
+
+  const discovery = discoverOpenScad({ openscadBin });
+
+  if (discovery.binary) {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-openscad-'));
+    const inputPath = path.join(tmpDir, 'input.scad');
+    const outputPath = path.join(tmpDir, outFilename);
+
+    fs.writeFileSync(inputPath, source, 'utf8');
+
+    const paramArgs = [];
+    for (const [key, val] of Object.entries(parameters)) {
+      if (typeof val === 'string') {
+        paramArgs.push('-D', `${key}="${val.replace(/"/g, '\\"')}"`);
+      } else if (typeof val === 'number' || typeof val === 'boolean') {
+        paramArgs.push('-D', `${key}=${val}`);
+      }
+    }
+
+    const exportArgs = [];
+    if (format === 'stl') {
+      exportArgs.push('--export-format', 'asciistl');
+    }
+
+    const args = ['-o', outputPath, ...exportArgs, ...paramArgs, inputPath];
+
+    try {
+      const proc = await runProcessImpl(discovery.binary, args, {
+        cwd: tmpDir,
+        timeoutMs,
+        maxBytes: 16 * 1024 * 1024,
+      });
+
+      if (!fs.existsSync(outputPath)) {
+        throw new Error(
+          proc.stderr || proc.stdout || `OpenSCAD failed to emit ${outFilename} with exit code ${proc.code}`
+        );
+      }
+
+      const buffer = fs.readFileSync(outputPath);
+      const isText = !buffer.includes(0);
+      const artifactContent = isText ? buffer.toString('utf8') : buffer.toString('base64');
+      const durationMs = Date.now() - started;
+
+      return {
+        success: true,
+        engine: 'openscad-native',
+        binary: discovery.binary,
+        outputFormat: format,
+        filename: outFilename,
+        mimeType,
+        sizeBytes: buffer.length,
+        durationMs,
+        artifactContent,
+        isBase64: !isText,
+        logs: [
+          `[KERNEL] OpenSCAD Native Compiler (${discovery.source})`,
+          `[PARAMETERS] Injected ${Object.keys(parameters).length} dynamic variables`,
+          `[OUTPUT] Generated ${outFilename} (${buffer.length} bytes) in ${durationMs}ms`,
+          ...(proc.stderr ? [proc.stderr.trim()] : []),
+        ],
+      };
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  }
+
+  // 2. Check if containerized Docker CAD service is available
+  try {
+    const dockerHealth = await probeDockerServiceHealth();
+    if (dockerHealth.available && dockerHealth.tools?.openscad?.installed) {
+      const dockerResult = await executeOpenScadDocker({
+        source,
+        outputFormat: format,
+        parameters,
+        filename: outFilename,
+        timeoutMs,
+      });
+      return {
+        ...dockerResult,
+        engine: 'openscad-docker',
+      };
+    }
+  } catch {
+    // Docker service error/unavailable -> fall through to procedural fallback
+  }
+
+  // Graceful fallback for headless or restricted environments lacking OpenSCAD executable
+  const durationMs = Date.now() - started;
+  const nameSlug = outFilename.replace(/\.[^/.]+$/, '');
+  let artifactContent = '';
+
+  if (format === 'stl') {
+    const w = Number(parameters.deskWidth || parameters.unitWidth || 48) * 0.0254;
+    const d = Number(parameters.deskDepth || parameters.unitDepth || 24) * 0.0254;
+    const h = Number(parameters.deskHeight || parameters.unitHeight || 30) * 0.0254;
+
+    const facets = [
+      `  facet normal 0 0 1\n    outer loop\n      vertex 0 0 ${h}\n      vertex ${w} 0 ${h}\n      vertex ${w} ${d} ${h}\n    endloop\n  endfacet`,
+      `  facet normal 0 0 1\n    outer loop\n      vertex 0 0 ${h}\n      vertex ${w} ${d} ${h}\n      vertex 0 ${d} ${h}\n    endloop\n  endfacet`,
+      `  facet normal 0 0 -1\n    outer loop\n      vertex 0 0 0\n      vertex ${w} ${d} 0\n      vertex ${w} 0 0\n    endloop\n  endfacet`,
+      `  facet normal 0 0 -1\n    outer loop\n      vertex 0 0 0\n      vertex 0 ${d} 0\n      vertex ${w} ${d} 0\n    endloop\n  endfacet`,
+    ];
+    artifactContent = `solid ${nameSlug}\n${facets.join('\n')}\nendsolid ${nameSlug}`;
+  } else if (format === 'dxf') {
+    artifactContent = '0\nSECTION\n2\nHEADER\n0\nENDSEC\n0\nSECTION\n2\nENTITIES\n0\nENDSEC\n0\nEOF\n';
+  } else {
+    artifactContent = source;
+  }
+
+  return {
+    success: true,
+    engine: 'procedural-fallback',
+    binary: null,
+    outputFormat: format,
+    filename: outFilename,
+    mimeType,
+    sizeBytes: Buffer.byteLength(artifactContent),
+    durationMs,
+    artifactContent,
+    isBase64: false,
+    logs: [
+      '[FALLBACK] OpenSCAD binary not detected; procedural synthesis engine used.',
+      `[OUTPUT] Synthesized ${outFilename} in ${durationMs}ms`,
+    ],
+  };
+}
+
+export { discoverOpenScad, openScadStatus };

package/src/lib/cad/project-cli.d.ts

@@ -0,0 +1,2 @@
+export function localProjectRuntime(root?: string, onProjectChanged?: (row: any)=>void): {execute(name: string,args?: any): Promise<any>; catalog(): any[]};
+export function runProjectCli(args: string[]): Promise<void>;

package/src/lib/cad/project-cli.js

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {runProjectWorkflow,CAD_PROJECT_WORKFLOWS} from './project-workflows.js';
+import {FileProjectStore} from './project-store.js';
+import {createProjectRuntime} from './project-runtime.js';
+export function localProjectRuntime(root=process.cwd(),onProjectChanged){
+ return createProjectRuntime({store:new FileProjectStore(path.join(root,'.agentsam/cad/projects')),artifactRoot:path.join(root,'.agentsam/cad/artifacts'),onProjectChanged});
+}
+export async function runProjectCli(args){
+ if(!args.length||args.includes('--help')){console.log('agentsam cad project <get|validate|apply|save|restore|build|inspect|render|export|tools> <request.json> [--root <project-directory>]');return;}
+ const names={get:'design_project_get',validate:'design_project_validate',apply:'design_apply_operation',save:'design_project_save',restore:'design_project_restore',build:'design_model_build',inspect:'design_model_inspect',render:'design_model_render',export:'design_model_export'};
+ const rootIndex=args.indexOf('--root'),root=rootIndex<0?process.cwd():path.resolve(args[rootIndex+1]);
+ const runtime=localProjectRuntime(root);
+ if(args[0]==='workflows'){console.log(JSON.stringify(CAD_PROJECT_WORKFLOWS));return;}
+ if(args[0]==='workflow'){const input=JSON.parse(fs.readFileSync(args[2]==='-'?0:args[2],'utf8'));console.log(JSON.stringify(await runProjectWorkflow(runtime,args[1],input,{evidenceRoot:path.join(root,'.agentsam/cad/workflow-runs')})));return;}
+ if(args[0]==='invoke'){const input=JSON.parse(Buffer.from(args[2],'base64url').toString('utf8'));console.log(JSON.stringify(await runtime.execute(args[1],input)));return;}
+ if(args[0]==='tools'){console.log(JSON.stringify(runtime.catalog()));return;}
+ const tool=names[args[0]];if(!tool)throw new Error('unknown_project_command');
+ const request=JSON.parse(fs.readFileSync(args[1]==='-'?0:args[1],'utf8'));
+ console.log(JSON.stringify(await runtime.execute(tool,request)));
+}

package/src/lib/cad/project-contract.d.ts

@@ -0,0 +1,3 @@
+export function validateProject(project: any): {valid: boolean; errors: string[]};
+export function requireValidProject(project: any): any;
+export function applyProjectOperation(project: any, operation: any): any;

package/src/lib/cad/project-contract.js

@@ -0,0 +1 @@
+export * from '../../../apps/cad-creator/shared/cad/src/domain/project-contract.js';

package/src/lib/cad/project-recipe.js

@@ -0,0 +1,30 @@
+import {requireValidProject} from './project-contract.js';
+// Native geometry is metres, Z-up. Names preserve editable element identifiers.
+export function projectToBlenderRecipe(project) {
+ requireValidProject(project);
+ if((project.parametricObjects||[]).length)throw new Error('parametric_objects_require_compilation');
+ if(project.roofType!=='none')throw new Error('roof_geometry_not_supported_yet');
+ const operations=[{op:'clear_scene'}], m=0.0254;
+ const box=(name,x,y,z,w,d,h,a=0)=>operations.push({op:'add',primitive:'cube',name,size:1,location:[x*m,y*m,z*m],scale:[w*m,d*m,h*m],rotation:[0,0,a]});
+ for(const w of project.walls){
+  const len=Math.hypot(w.x2-w.x1,w.y2-w.y1),a=Math.atan2(w.y2-w.y1,w.x2-w.x1);
+  const opening=[...project.doors,...project.windows].filter(e=>e.wallId===w.id).map(e=>({start:e.distanceAlongWall*len-e.width/2,end:e.distanceAlongWall*len+e.width/2,z:e.elevation??0,h:e.height})).sort((a,b)=>a.start-b.start);
+  let cursor=0,part=0;
+  const segment=(s,e,z,h)=>{if(e-s>1e-6&&h>1e-6){const t=(s+e)/2;box(w.id+':'+part++,w.x1+Math.cos(a)*t,w.y1+Math.sin(a)*t,z+h/2,e-s,w.thickness,h,a);}};
+  for(const o of opening){if(o.start<cursor-1e-6)throw new Error('overlapping_openings:'+w.id);segment(cursor,o.start,0,w.height3D);segment(o.start,o.end,0,o.z);segment(o.start,o.end,o.z+o.h,w.height3D-o.z-o.h);cursor=o.end;}
+  segment(cursor,len,0,w.height3D);
+ }
+ // Only axis-aligned rectangular floor polygons are currently compiled; fail explicitly for others.
+ for(const r of project.rooms){
+  const xs=[...new Set(r.points.map(p=>p[0]))],ys=[...new Set(r.points.map(p=>p[1]))];
+  if(r.points.length!==4||xs.length!==2||ys.length!==2||new Set(r.points.map(p=>p.join(','))).size!==4||r.points.some((p,i)=>{const q=r.points[(i+1)%4];return p[0]!==q[0]&&p[1]!==q[1];}))throw new Error('non_rectangular_floor:'+r.id);
+  box(r.id,(xs[0]+xs[1])/2,(ys[0]+ys[1])/2,-2,Math.abs(xs[1]-xs[0]),Math.abs(ys[1]-ys[0]),4);
+ }
+ for(const f of project.furniture)box(f.id,f.x,f.y,f.h/2,f.w,f.d,f.h,(f.rotation||0)*Math.PI/180);
+ const xs=project.walls.flatMap(w=>[w.x1,w.x2]),ys=project.walls.flatMap(w=>[w.y1,w.y2]);
+ if(!xs.length)throw new Error('model_requires_walls');
+ const cx=(Math.min(...xs)+Math.max(...xs))/2*m,cy=(Math.min(...ys)+Math.max(...ys))/2*m, span=Math.max(Math.max(...xs)-Math.min(...xs),Math.max(...ys)-Math.min(...ys))*m;
+ operations.push({op:'add_camera',name:'Courtyard',location:[cx,cy+span*1.4,span],rotation:[Math.atan(1.4),0,Math.PI],lens:40,active:true},{op:'add_light',name:'Sun',type:'SUN',energy:3,rotation:[0.5,-0.4,-0.5]});
+ if(operations.length>256)throw new Error('recipe_operation_limit_exceeded');
+ return {schema_version:1,units:{system:'METRIC',scale_length:1,length_unit:'METERS'},operations};
+}

package/src/lib/cad/project-runtime.d.ts

@@ -0,0 +1,2 @@
+export const CAD_PROJECT_TOOLS: any[];
+export function createProjectRuntime(options: any): {execute(name: string,args?: any): Promise<any>;catalog(): any[]};

package/src/lib/cad/project-runtime.js

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {validateProject,applyProjectOperation} from './project-contract.js';
+import {projectToBlenderRecipe} from './project-recipe.js';
+import {blenderBuild,blenderInspect,blenderRenderPreview,blenderExport} from './blender.js';
+import {CAD_PROJECT_TOOLS} from '../../../apps/cad-creator/shared/cad/src/domain/project-tools.js';
+export {CAD_PROJECT_TOOLS};
+export function createProjectRuntime({store,artifactRoot,native={blenderBuild,blenderInspect,blenderRenderPreview,blenderExport},onProjectChanged=()=>{}}){
+ const root=path.resolve(artifactRoot);
+ async function execute(name,args={}){
+  const descriptor=CAD_PROJECT_TOOLS.find(t=>t.name===name);
+  if(!descriptor)throw new Error('unknown_design_tool');
+  if(!args||typeof args!=='object'||Array.isArray(args))throw new Error('invalid_tool_input');
+  for(const key of Object.keys(args))if(!Object.hasOwn(descriptor.input_schema.properties,key))throw new Error('unknown_argument:'+key);
+  for(const key of descriptor.input_schema.required)if(args[key]===undefined)throw new Error('argument_required:'+key);
+  for(const key of ['revision','expected_revision'])if(args[key]!==undefined&&(!Number.isInteger(args[key])||args[key]<(key==='revision'?1:0)))throw new Error('invalid_'+key);
+  if(args.project_id!==undefined&&!/^[A-Za-z0-9_-]{1,100}$/.test(args.project_id))throw new Error('invalid_project_id');
+  if(name==='design_project_validate'&&args.project===undefined&&args.project_id===undefined)throw new Error('argument_required:project_or_project_id');
+  if(name==='design_project_validate')return validateProject(args.project??(await store.read(args.project_id,args.revision)).project);
+  if(name==='design_project_get'){const row=await store.read(args.project_id,args.revision);if(args.expected_content_hash&&row.content_hash!==args.expected_content_hash)throw new Error('reopen_verification_failed');return row;}
+  let saved;
+  if(name==='design_project_save')saved=await store.save(args.project,args.expected_revision,args.message);
+  if(name==='design_project_restore')saved=await store.restore(args.project_id,args.revision,args.expected_revision);
+  if(name==='design_apply_operation'){
+   const current=await store.read(args.project_id);
+   if(current.revision!==args.expected_revision)throw new Error('revision_conflict');
+   saved=await store.save(applyProjectOperation(current.project,args.operation),args.expected_revision,args.message??args.operation.type);
+  }
+  if(saved){await onProjectChanged(saved);return saved;}
+  const row=await store.read(args.project_id,args.revision);
+  // Store validates ids. Artifact paths never come from a caller-supplied path.
+  if(!/^[A-Za-z0-9_-]{1,100}$/.test(row.project.id))throw new Error('invalid_project_id');
+  const dir=path.join(root,row.project.id,String(row.revision)), blend=path.join(dir,'model.blend'), receipt=path.join(dir,'build.json');
+  fs.mkdirSync(dir,{recursive:true});
+  let result;
+  if(name==='design_model_build'){
+   if(fs.existsSync(receipt)){const prior=JSON.parse(fs.readFileSync(receipt,'utf8'));if(prior.content_hash!==row.content_hash)throw new Error('artifact_revision_conflict');}
+   result=await native.blenderBuild({output:blend,recipe:projectToBlenderRecipe(row.project),timeoutSeconds:120});
+   fs.writeFileSync(receipt,JSON.stringify({content_hash:row.content_hash,artifact:result.artifact}));
+  }else{
+   const prior=JSON.parse(fs.readFileSync(receipt,'utf8'));
+   if(prior.content_hash!==row.content_hash)throw new Error('artifact_revision_conflict');
+   const {sha256File}=await import('./blender.js');
+   if(sha256File(blend)!==prior.artifact.sha256)throw new Error('model_digest_mismatch');
+   if(name==='design_model_inspect')result=await native.blenderInspect({input:blend});
+   if(name==='design_model_render')result=await native.blenderRenderPreview({input:blend,output:path.join(dir,'courtyard.png'),width:1024,height:768,timeoutSeconds:120});
+   if(name==='design_model_export'){if(!['glb','stl','obj'].includes(args.format??'glb'))throw new Error('invalid_format');result=await native.blenderExport({input:blend,output:path.join(dir,'model.'+(args.format??'glb')),format:args.format??'glb'});}
+  }
+  const out={...result,project_id:row.project.id,revision:row.revision,content_hash:row.content_hash};
+  fs.writeFileSync(path.join(dir,name+'.json'),JSON.stringify(out,null,2));return out;
+ }
+ return {execute,catalog:()=>CAD_PROJECT_TOOLS};
+}

package/src/lib/cad/project-store.js

@@ -0,0 +1,25 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash, randomUUID} from 'node:crypto';
+import {requireValidProject} from './project-contract.js';
+export const projectHash=p=>createHash('sha256').update(JSON.stringify(p)).digest('hex');
+// Immutable revision files plus one atomically replaced pointer. Single host; no distributed claims.
+export class FileProjectStore {
+ constructor(root){this.root=path.resolve(root);}
+ dir(id){if(!/^[A-Za-z0-9_-]{1,100}$/.test(id))throw new Error('invalid_project_id');return path.join(this.root,id);}
+ async read(id,revision){const d=this.dir(id);let r=revision;if(r==null)r=JSON.parse(fs.readFileSync(path.join(d,'head.json'),'utf8')).revision;if(!Number.isSafeInteger(r)||r<1)throw new Error('invalid_revision');return JSON.parse(fs.readFileSync(path.join(d,r+'.json'),'utf8'));}
+ async save(project,expectedRevision,message='Saved project'){
+  requireValidProject(project);if(!Number.isSafeInteger(expectedRevision)||expectedRevision<0)throw new Error('expected_revision_required');
+  const d=this.dir(project.id);fs.mkdirSync(d,{recursive:true});const lock=path.join(d,'write.lock');
+  let fd;try{fd=fs.openSync(lock,'wx');}catch{throw new Error('project_busy');}
+  try{
+   let revision=0;try{revision=(await this.read(project.id)).revision;}catch(e){if(e.code!=='ENOENT')throw e;}
+   if(revision!==expectedRevision)throw new Error('revision_conflict');
+   const next={...structuredClone(project),version:revision+1,updatedAt:Date.now()};
+   const row={project:next,revision:revision+1,content_hash:projectHash(next),message,created_at:Math.floor(Date.now()/1000)};
+   fs.writeFileSync(path.join(d,row.revision+'.json'),JSON.stringify(row),{flag:'wx'});
+   const tmp=path.join(d,randomUUID()+'.tmp');fs.writeFileSync(tmp,JSON.stringify({revision:row.revision}));fs.renameSync(tmp,path.join(d,'head.json'));return row;
+  }finally{fs.closeSync(fd);fs.unlinkSync(lock);}
+ }
+ async restore(id,revision,expectedRevision){const past=await this.read(id,revision);return this.save(past.project,expectedRevision,'Restored revision '+revision);}
+}

package/src/lib/cad/project-workflows.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+export const CAD_PROJECT_WORKFLOWS=[
+ {key:'cad.house_baseline',description:'Validate, save, reopen, build, inspect, render and export an editable courtyard baseline.',requires:['project.valid_candidate','native.blender.available'],provides:['project.saved','model.inspected','preview.rendered','export.glb'],steps:['validate','save','reopen','build','inspect','render','export']},
+ {key:'cad.edit_preview',description:'Read, atomically edit, reopen, build, inspect, render and export a saved project.',requires:['project.saved','project.expected_revision','native.blender.available'],provides:['project.revised','model.inspected','preview.rendered','export.glb'],steps:['read','edit','reopen','build','inspect','render','export']}
+];
+const tools={validate:'design_project_validate',save:'design_project_save',read:'design_project_get',edit:'design_apply_operation',reopen:'design_project_get',build:'design_model_build',inspect:'design_model_inspect',render:'design_model_render',export:'design_model_export'};
+export async function runProjectWorkflow(runtime,key,input,{evidenceRoot}={}){
+ const definition=CAD_PROJECT_WORKFLOWS.find(w=>w.key===key);if(!definition)throw new Error('unknown_cad_workflow');
+ const evidence={run_id:randomUUID(),workflow_key:key,status:'running',started_at:Math.floor(Date.now()/1000),steps:[]};
+ const record=()=>{if(evidenceRoot){fs.mkdirSync(evidenceRoot,{recursive:true});const file=path.join(evidenceRoot,evidence.run_id+'.json');fs.writeFileSync(file+'.tmp',JSON.stringify(evidence,null,2));fs.renameSync(file+'.tmp',file);}};
+ let row;
+ record();
+ try{
+ for(const step of definition.steps){
+  const args=step==='validate'?{project:input.project}:step==='save'?{project:input.project,expected_revision:input.expected_revision??0}:
+   step==='read'?{project_id:input.project_id}:step==='edit'?{project_id:input.project_id,expected_revision:input.expected_revision,operation:input.operation}:
+   {...{project_id:row.project.id,revision:row.revision},...(step==='export'?{format:'glb'}:{})};
+  if(step==='edit'&&row.revision!==input.expected_revision)throw new Error('revision_conflict');
+  const result=await runtime.execute(tools[step],args);
+  if(step==='validate'&&!result.valid)throw new Error('project_invalid:'+JSON.stringify(result.errors));
+  if(step==='reopen'&&(result.content_hash!==row.content_hash||result.revision!==row.revision))throw new Error('reopen_verification_failed');
+  if(['save','read','edit','reopen'].includes(step))row=result;
+  evidence.steps.push({node_key:step,tool_name:tools[step],status:'completed',result});record();
+ }
+ evidence.status='completed';evidence.verified_results={project_id:row.project.id,revision:row.revision,content_hash:row.content_hash,facts:definition.provides};
+ }catch(error){evidence.status='failed';evidence.error=error.message;throw error;}
+ finally{evidence.completed_at=Math.floor(Date.now()/1000);record();}
+ return evidence;
+}

package/src/lib/cad-docker.js

@@ -48,6 +48,10 @@ export function generateCadDocker(opts = {}) {
 
   const packages = ['python3', 'ca-certificates', 'passwd', ...new Set(tools.flatMap(tool => APT_PACKAGES[tool]))];
   const q = JSON.stringify;
+  const copyLines = ['COPY server.py /srv/server.py'];
+  if (tools.includes('freecad')) copyLines.push('COPY freecad/ /srv/freecad/');
+  if (tools.includes('blender')) copyLines.push('COPY blender/ /srv/blender/');
+
   const dockerfile = `# AgentSam CAD runtime SHA-256: ${runtimeDigest()}
 # Tools: ${tools.join(', ')}
 FROM debian:bookworm-slim
@@ -59,7 +63,7 @@ RUN apt-get update \\
  && mkdir -p /srv /work \\
  && chown -R cad:cad /work
 WORKDIR /srv
-COPY server.py /srv/server.py
+${copyLines.join('\n')}
 ENV PORT=${port} AGENTSAM_CAD_TOKEN_FILE=/config/service.token AGENTSAM_CAD_WORK_ROOT=/work AGENTSAM_CAD_TOOLS=${tools.join(',')} QT_QPA_PLATFORM=offscreen PYTHONUNBUFFERED=1 HOME=/tmp/home XDG_CACHE_HOME=/tmp/cache XDG_CONFIG_HOME=/tmp/config
 EXPOSE ${port}
 USER cad
@@ -128,10 +132,25 @@ export function prepareCadDeployment(targetDir, opts = {}) {
   return { ...opts, configurationDir, tokenFile, tools };
 }
 
-export function stageCadContext(versionDir) {
+export function stageCadContext(versionDir, opts = {}) {
   const context = path.join(versionDir, 'context');
   fs.mkdirSync(context, { recursive: true });
   fs.copyFileSync(path.join(sdkRoot, CAD_SERVER_FILE), path.join(context, 'server.py'));
+  const tools = opts.tools ? normalizeCadTools(opts.tools) : [];
+  if (tools.includes('freecad')) {
+    const freecadAdapter = path.join(sdkRoot, 'services/cad/freecad/adapter.py');
+    if (fs.existsSync(freecadAdapter)) {
+      fs.mkdirSync(path.join(context, 'freecad'), { recursive: true });
+      fs.copyFileSync(freecadAdapter, path.join(context, 'freecad', 'adapter.py'));
+    }
+  }
+  if (tools.includes('blender')) {
+    const blenderAdapter = path.join(sdkRoot, 'services/cad/blender/adapter.py');
+    if (fs.existsSync(blenderAdapter)) {
+      fs.mkdirSync(path.join(context, 'blender'), { recursive: true });
+      fs.copyFileSync(blenderAdapter, path.join(context, 'blender', 'adapter.py'));
+    }
+  }
   return context;
 }
 

package/src/lib/cli-preferences.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { getProjectName, tryReadProjectConfig } from './project-config.js';
+import { mergeModelReference } from '../models/index.js';
 
 export const CLI_PREFERENCES_SCHEMA = 'agentsam-cli-preferences-v3';
 export const LEGACY_CLI_PREFERENCES_SCHEMAS = new Set(['agentsam-cli-preferences-v1', 'agentsam-cli-preferences-v2']);
@@ -18,9 +19,19 @@ function gitValue(cwd, args) {
 
 export function findCliProjectRoot(startDir = process.cwd()) {
   const cwd = path.resolve(startDir);
+  // An explicit AgentSam project inside a larger Git checkout owns its own
+  // state. Git is the fallback boundary, not an override for that manifest.
+  let dir = cwd;
+  for (let i = 0; i < 16; i += 1) {
+    if (fs.existsSync(path.join(dir, '.agentsam', 'config.json'))) return dir;
+    if (fs.existsSync(path.join(dir, '.git'))) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
   const gitRoot = gitValue(cwd, ['rev-parse', '--show-toplevel']);
   if (gitRoot) return path.resolve(gitRoot);
-  let dir = cwd;
+  dir = cwd;
   for (let i = 0; i < 16; i += 1) {
     if (fs.existsSync(path.join(dir, '.agentsam', 'cli.json')) || fs.existsSync(path.join(dir, '.agentsam', 'config.json')) || fs.existsSync(path.join(dir, 'package.json'))) return dir;
     const parent = path.dirname(dir);
@@ -53,12 +64,16 @@ function safeModelSnapshot(value) {
     provider,
     provider_model_id: providerModelId,
     label: String(value.label || providerModelId),
+    kind: String(value.kind || 'unknown'),
+    description: value.description ? String(value.description) : null,
     availability: value.availability === 'available' ? 'available' : 'unverified',
     availability_source: String(value.availability_source || ''),
     context_window: Number.isFinite(Number(value.context_window)) && Number(value.context_window) > 0 ? Number(value.context_window) : null,
     context_window_source: String(value.context_window_source || 'unknown'),
     max_output_tokens: Number.isFinite(Number(value.max_output_tokens)) && Number(value.max_output_tokens) > 0 ? Number(value.max_output_tokens) : null,
     max_output_tokens_source: String(value.max_output_tokens_source || 'unknown'),
+    knowledge_cutoff: value.knowledge_cutoff ? String(value.knowledge_cutoff) : null,
+    default_reasoning_effort: value.default_reasoning_effort ? String(value.default_reasoning_effort) : null,
     reasoning_efforts: Array.isArray(value.reasoning_efforts) && value.reasoning_efforts.length ? value.reasoning_efforts.map(String) : ['auto'],
     service_tiers: Array.isArray(value.service_tiers) && value.service_tiers.length ? value.service_tiers.map(String) : ['default'],
     capabilities: value.capabilities && typeof value.capabilities === 'object' ? { ...value.capabilities } : {},
@@ -69,7 +84,7 @@ function safeModelSnapshot(value) {
 }
 
 function normalizePreferences(value = {}) {
-  const modelSnapshot = safeModelSnapshot(value.modelSnapshot);
+  const modelSnapshot = mergeModelReference(safeModelSnapshot(value.modelSnapshot));
   return {
     schemaVersion: CLI_PREFERENCES_SCHEMA,
     trustedDirectory: value.trustedDirectory === true,

package/src/lib/core-client.js

@@ -13,7 +13,7 @@ export function coreBaseUrl(env = process.env) {
 }
 
 function authOptions(options) {
-  if (typeof options === 'string') return { explicit: options };
+  if (typeof options === 'string') return { bearer: options };
   return options && typeof options === 'object' ? options : {};
 }
 
@@ -30,6 +30,7 @@ export async function resolveCoreAuthority(options = {}) {
     nowMs: resolvedOptions.nowMs,
     skewMs: resolvedOptions.skewMs,
     refreshImpl: resolvedOptions.refreshImpl,
+    forceRefresh: resolvedOptions.forceRefresh === true,
   });
   if (authority?.error) throw new Error(authority.error);
   if (!authority?.value) throw new Error('account_auth_required');
@@ -37,11 +38,22 @@ export async function resolveCoreAuthority(options = {}) {
 }
 
 async function authorizedHeaders(headers, options = {}) {
+  if (String(options?.bearer || '').trim()) {
+    return { headers: { ...headers, Authorization: `Bearer ${String(options.bearer).trim()}` }, authority: { kind: 'resolved_bearer' } };
+  }
   const authority = await resolveCoreAuthority(options);
-  return {
-    ...headers,
-    Authorization: `Bearer ${authority.value}`,
-  };
+  return { headers: { ...headers, Authorization: `Bearer ${authority.value}` }, authority };
+}
+
+async function authorizedFetch(url, init, options = {}) {
+  const baseHeaders = init.headers || {};
+  let resolved = await authorizedHeaders(baseHeaders, options);
+  let response = await (options.fetchImpl || fetch)(url, { ...init, headers: resolved.headers });
+  if (response.status === 401 && resolved.authority?.kind === 'browser_oauth' && options.forceRefresh !== true) {
+    resolved = await authorizedHeaders(baseHeaders, { ...options, forceRefresh: true });
+    response = await (options.fetchImpl || fetch)(url, { ...init, headers: resolved.headers });
+  }
+  return response;
 }
 
 async function responseJson(res) {
@@ -51,16 +63,16 @@ async function responseJson(res) {
 export async function postJson(path, body, options = {}) {
   const resolvedOptions = authOptions(options);
   const fetchImpl = resolvedOptions.fetchImpl || fetch;
-  const headers = await authorizedHeaders({
+  const headers = {
     'Content-Type': 'application/json',
     Accept: 'application/json',
-  }, resolvedOptions);
-  const res = await fetchImpl(`${coreBaseUrl(resolvedOptions.env || process.env)}${path}`, {
+  };
+  const res = await authorizedFetch(`${coreBaseUrl(resolvedOptions.env || process.env)}${path}`, {
     method: 'POST',
     headers,
     body: JSON.stringify(body ?? {}),
     signal: resolvedOptions.signal,
-  });
+  }, { ...resolvedOptions, fetchImpl });
   const data = await responseJson(res);
   if (!res.ok) {
     const msg = data?.error || data?.message || `HTTP ${res.status}`;
@@ -72,15 +84,22 @@ export async function postJson(path, body, options = {}) {
 export async function getJson(path, options = {}) {
   const resolvedOptions = authOptions(options);
   const fetchImpl = resolvedOptions.fetchImpl || fetch;
-  const headers = await authorizedHeaders({ Accept: 'application/json' }, resolvedOptions);
-  const res = await fetchImpl(`${coreBaseUrl(resolvedOptions.env || process.env)}${path}`, {
-    headers,
+  const res = await authorizedFetch(`${coreBaseUrl(resolvedOptions.env || process.env)}${path}`, {
+    headers: { Accept: 'application/json' },
     signal: resolvedOptions.signal,
-  });
+  }, { ...resolvedOptions, fetchImpl });
   const data = await responseJson(res);
   if (!res.ok) {
     const msg = data?.error || data?.message || `HTTP ${res.status}`;
-    throw new Error(String(msg));
+    const error = new Error(String(msg));
+    // Previously discarded: status code and which endpoint failed. Both are
+    // known here and cost nothing to keep -- callers (whoami, etc.) can now
+    // surface "Unauthorized (HTTP 401 from /api/sdk/context)" instead of a
+    // bare "Unauthorized" with no way to tell what actually failed.
+    error.status = res.status;
+    error.endpoint = path;
+    error.requestId = res.headers?.get?.('cf-ray') || data?.request_id || null;
+    throw error;
   }
   return data;
 }
@@ -91,16 +110,16 @@ export async function getJson(path, options = {}) {
 export async function streamScaffold(body, onEvent, options = {}) {
   const resolvedOptions = authOptions(options);
   const fetchImpl = resolvedOptions.fetchImpl || fetch;
-  const headers = await authorizedHeaders({
+  const headers = {
     'Content-Type': 'application/json',
     Accept: 'application/x-ndjson',
-  }, resolvedOptions);
-  const res = await fetchImpl(`${coreBaseUrl(resolvedOptions.env || process.env)}/api/sdk/scaffold`, {
+  };
+  const res = await authorizedFetch(`${coreBaseUrl(resolvedOptions.env || process.env)}/api/sdk/scaffold`, {
     method: 'POST',
     headers,
     body: JSON.stringify(body),
     signal: resolvedOptions.signal,
-  });
+  }, { ...resolvedOptions, fetchImpl });
   if (!res.ok) {
     const data = await responseJson(res);
     throw new Error(data?.error || `scaffold HTTP ${res.status}`);

package/src/lib/deploy/local-studio.js

@@ -120,7 +120,7 @@ export function writeDeployReceipt(appRoot, receipt) {
 export function wranglerDeployCommand(target, { dryRun = false } = {}) {
   const args = ['wrangler', ...target.wranglerArgs];
   if (dryRun) args.push('--dry-run');
-  return { cwd: target.appRoot, args, bin: 'npx' };
+  return { cwd: target.appRoot, args, bin: process.platform === 'win32' ? 'npx.cmd' : 'npx' };
 }
 
 export function isLocalStudioCheckout(cwd = process.cwd()) {
@@ -217,16 +217,17 @@ export async function runLocalStudioDeploy({
   }
 
   const env = { ...process.env, ...envFile.vars };
-  const lock = spawnSync('npm', ['run', 'verify:npm10-lock'], { cwd: target.appRoot, env, encoding: 'utf8' });
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const lock = spawnSync(npmCmd, ['run', 'verify:npm10-lock'], { cwd: target.appRoot, env, encoding: 'utf8', shell: process.platform === 'win32' });
   if (lock.status !== 0) throw new Error(lock.stderr || lock.stdout || 'verify:npm10-lock failed');
   if (!skipBuild) {
-    const build = spawnSync('npm', ['run', 'build'], { cwd: target.appRoot, env, encoding: 'utf8' });
+    const build = spawnSync(npmCmd, ['run', 'build'], { cwd: target.appRoot, env, encoding: 'utf8', shell: process.platform === 'win32' });
     if (build.status !== 0) throw new Error(build.stderr || build.stdout || 'build failed');
-    const verify = spawnSync('npm', ['run', 'cf:verify-output'], { cwd: target.appRoot, env, encoding: 'utf8' });
+    const verify = spawnSync(npmCmd, ['run', 'cf:verify-output'], { cwd: target.appRoot, env, encoding: 'utf8', shell: process.platform === 'win32' });
     if (verify.status !== 0) throw new Error(verify.stderr || verify.stdout || 'cf:verify-output failed');
   }
   const cmd = wranglerDeployCommand(target, { dryRun });
-  const deployed = spawnSync(cmd.bin, cmd.args, { cwd: cmd.cwd, env, encoding: 'utf8' });
+  const deployed = spawnSync(cmd.bin, cmd.args, { cwd: cmd.cwd, env, encoding: 'utf8', shell: process.platform === 'win32' });
   const wranglerOut = `${deployed.stdout || ''}\n${deployed.stderr || ''}`;
   const workerVersion = parseWranglerVersionId(wranglerOut);
   if (deployed.status !== 0) {