@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.3

package/src/lib/cad/docker-executor.js

@@ -0,0 +1,352 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const DEFAULT_CAD_DOCKER_PORT = 8793;
+export const DEFAULT_CAD_DOCKER_URL = `http://127.0.0.1:${DEFAULT_CAD_DOCKER_PORT}`;
+
+function isFile(value) {
+  try {
+    return Boolean(value) && fs.existsSync(value) && fs.statSync(value).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolves the Docker CAD service URL and authentication token.
+ * Searches environment variables and local configuration token files.
+ */
+export function resolveDockerServiceConfig(options = {}) {
+  const env = options.env || process.env;
+  const rawUrl = String(
+    options.serviceUrl ||
+    env.AGENTSAM_CAD_SERVICE_URL ||
+    DEFAULT_CAD_DOCKER_URL
+  ).trim();
+  const url = rawUrl.replace(/\/+$/, '');
+
+  // AGENTSAM_CAD_TOKEN is an explicit override; otherwise reuse
+  // AGENTSAM_BRIDGE_KEY, the machine-to-machine secret iam-cad-worker's
+  // /cad/run lane already trusts, rather than requiring a second credential
+  // provisioned just for this route.
+  let token = String(
+    options.token ||
+    env.AGENTSAM_CAD_TOKEN ||
+    env.AGENTSAM_BRIDGE_KEY ||
+    ''
+  ).trim();
+
+  if (!token) {
+    const cwd = options.cwd || process.cwd();
+    const candidates = [
+      path.join(cwd, '.agentsam/docker/cad/agentsam-cad/service.token'),
+      path.join(os.homedir(), '.agentsam/docker/cad/agentsam-cad/service.token'),
+      path.join(cwd, '.agentsam/docker/cad/service.token'),
+      path.join(os.homedir(), '.agentsam/docker/cad/service.token'),
+    ];
+
+    for (const candidate of candidates) {
+      if (isFile(candidate)) {
+        try {
+          const contents = fs.readFileSync(candidate, 'utf8').trim();
+          if (contents) {
+            token = contents;
+            break;
+          }
+        } catch {}
+      }
+    }
+  }
+
+  return {
+    url,
+    token: token || null,
+  };
+}
+
+/**
+ * Quickly checks if the CAD Docker container service is running and healthy.
+ */
+export async function probeDockerServiceHealth(options = {}) {
+  const { url, token } = resolveDockerServiceConfig(options);
+  const fetchFn = options.fetchImpl || globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? 2500;
+
+  if (typeof fetchFn !== 'function') {
+    return {
+      available: false,
+      url,
+      error: 'fetch is not available in runtime',
+    };
+  }
+
+  const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
+
+  try {
+    const headers = {};
+    if (token) {
+      headers.Authorization = `Bearer ${token}`;
+    }
+
+    const res = await fetchFn(`${url}/healthz`, {
+      method: 'GET',
+      headers,
+      signal: controller?.signal,
+    });
+
+    if (timer) clearTimeout(timer);
+
+    if (!res.ok) {
+      return {
+        available: false,
+        url,
+        status: `http_${res.status}`,
+        error: `HTTP ${res.status}: ${res.statusText}`,
+      };
+    }
+
+    const data = await res.json();
+    return {
+      available: Boolean(data?.ok),
+      url,
+      service: data?.service || 'agentsam-cad',
+      version: data?.version || null,
+      tools: data?.tools || {},
+      endpoints: data?.endpoints || {},
+    };
+  } catch (err) {
+    if (timer) clearTimeout(timer);
+    return {
+      available: false,
+      url,
+      error: err?.message || 'Connection refused',
+    };
+  }
+}
+
+/**
+ * Compiles OpenSCAD script using the containerized Docker CAD service.
+ */
+export async function executeOpenScadDocker(options = {}) {
+  const { url, token } = resolveDockerServiceConfig(options);
+  const fetchFn = options.fetchImpl || globalThis.fetch;
+  const startTime = Date.now();
+  const format = String(options.outputFormat || options.format || 'stl').toLowerCase().replace(/^\./, '');
+  const filename = options.filename || `model.${format}`;
+  const timeoutMs = options.timeoutMs || 30_000;
+
+  const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
+
+  try {
+    const headers = { 'Content-Type': 'application/json' };
+    if (token) headers.Authorization = `Bearer ${token}`;
+
+    const res = await fetchFn(`${url}/v1/openscad/compile`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        source: options.source,
+        format,
+        parameters: options.parameters || {},
+        filename,
+        timeout_seconds: Math.ceil(timeoutMs / 1000),
+      }),
+      signal: controller?.signal,
+    });
+
+    if (timer) clearTimeout(timer);
+
+    const body = await res.json();
+    if (!res.ok || !body?.ok) {
+      throw new Error(body?.error || `Docker OpenSCAD compilation failed with HTTP ${res.status}`);
+    }
+
+    const durationMs = Date.now() - startTime;
+    const base64Data = body.artifact_base64 || '';
+    const buffer = Buffer.from(base64Data, 'base64');
+    const isText = format === 'stl' || format === 'dxf' || format === 'svg' || format === 'scad' || format === 'csg';
+    const artifactContent = isText ? buffer.toString('utf8') : base64Data;
+
+    const mimeType =
+      format === 'stl'
+        ? 'model/stl'
+        : format === 'dxf'
+          ? 'image/vnd.dxf'
+          : format === 'svg'
+            ? 'image/svg+xml'
+            : format === '3mf'
+              ? 'model/3mf'
+              : 'text/plain';
+
+    return {
+      success: true,
+      engine: 'openscad-docker',
+      artifactContent,
+      artifactBase64: base64Data,
+      mimeType,
+      filename: body.filename || filename,
+      outputFormat: format,
+      sizeBytes: body.size_bytes || buffer.length,
+      sha256: body.sha256 || null,
+      durationMs,
+      executionTimeMs: durationMs,
+      logs: [
+        `[KERNEL] AgentSam CAD Docker Service (${url})`,
+        `[CONTAINER] Executed in isolated read-only debian container`,
+        ...(body.logs ? String(body.logs).split(/\r?\n/).filter(Boolean) : []),
+      ],
+    };
+  } catch (err) {
+    if (timer) clearTimeout(timer);
+    throw err;
+  }
+}
+
+/**
+ * Builds precision solid geometry using FreeCAD OpenCASCADE kernel inside Docker.
+ */
+export async function executeFreeCadDocker(options = {}) {
+  const { url, token } = resolveDockerServiceConfig(options);
+  const fetchFn = options.fetchImpl || globalThis.fetch;
+  const startTime = Date.now();
+  const format = String(options.format || 'step').toLowerCase().replace(/^\./, '');
+  const filename = options.filename || `model.${format}`;
+  const timeoutMs = options.timeoutMs || 35_000;
+
+  const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
+
+  try {
+    const headers = { 'Content-Type': 'application/json' };
+    if (token) headers.Authorization = `Bearer ${token}`;
+
+    const res = await fetchFn(`${url}/v1/freecad/execute`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        operations: options.operations || options.recipe?.operations || [],
+        recipe: options.recipe,
+        format,
+        filename,
+        timeout_seconds: Math.ceil(timeoutMs / 1000),
+      }),
+      signal: controller?.signal,
+    });
+
+    if (timer) clearTimeout(timer);
+
+    const body = await res.json();
+    if (!res.ok || !body?.ok) {
+      throw new Error(body?.error || `Docker FreeCAD execution failed with HTTP ${res.status}`);
+    }
+
+    const durationMs = Date.now() - startTime;
+    const base64Data = body.artifact_base64 || '';
+    const buffer = Buffer.from(base64Data, 'base64');
+
+    return {
+      ok: true,
+      success: true,
+      capability: 'freecad.build',
+      engine: 'freecad-docker',
+      format: body.format || format,
+      filename: body.filename || filename,
+      sizeBytes: body.size_bytes || buffer.length,
+      sha256: body.sha256 || null,
+      artifactBase64: base64Data,
+      artifactText: format === 'step' || format === 'stp' || format === 'brep' ? buffer.toString('utf8') : undefined,
+      metrics: body.metrics || {},
+      durationMs,
+      logs: [
+        `[KERNEL] AgentSam CAD Docker Service (${url})`,
+        `[CONTAINER] FreeCAD OpenCASCADE kernel execution`,
+        ...(body.logs ? String(body.logs).split(/\r?\n/).filter(Boolean) : []),
+      ],
+    };
+  } catch (err) {
+    if (timer) clearTimeout(timer);
+    throw err;
+  }
+}
+
+/**
+ * Builds or renders 3D scenes using Blender inside Docker.
+ */
+export async function executeBlenderDocker(options = {}) {
+  const { url, token } = resolveDockerServiceConfig(options);
+  const fetchFn = options.fetchImpl || globalThis.fetch;
+  const startTime = Date.now();
+  const format = String(options.format || 'glb').toLowerCase().replace(/^\./, '');
+  const operation = options.operation || 'build';
+  const filename = options.filename || `model.${format}`;
+  const timeoutMs = options.timeoutMs || 45_000;
+
+  // Full operation-specific request (recipe for build; scene/camera/width/height
+  // for render_preview; format/objects/collection/apply_modifiers for export;
+  // {} for inspect) — falls back to the legacy recipe/operations-only shape
+  // for callers that haven't been updated.
+  const requestPayload = options.request
+    || (options.recipe ? { recipe: options.recipe }
+      : (options.operations ? { recipe: { schema_version: 1, operations: options.operations } } : {}));
+
+  const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
+
+  try {
+    const headers = { 'Content-Type': 'application/json' };
+    if (token) headers.Authorization = `Bearer ${token}`;
+
+    const res = await fetchFn(`${url}/v1/blender/execute`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        operation,
+        request: { format, ...requestPayload },
+        // Base64 bytes of the source .blend when this operation edits an
+        // existing file (inspect/render_preview/export/edit-build); the
+        // container has no access to the caller's local filesystem.
+        input_base64: options.inputBase64 || null,
+        filename,
+        timeout_seconds: Math.ceil(timeoutMs / 1000),
+      }),
+      signal: controller?.signal,
+    });
+
+    if (timer) clearTimeout(timer);
+
+    const body = await res.json();
+    if (!res.ok || !body?.ok) {
+      throw new Error(body?.error || `Docker Blender execution failed with HTTP ${res.status}`);
+    }
+
+    const durationMs = Date.now() - startTime;
+    const base64Data = body.artifact_base64 || '';
+    const buffer = Buffer.from(base64Data, 'base64');
+
+    return {
+      ok: true,
+      success: true,
+      capability: `blender.${operation}`,
+      engine: 'blender-docker',
+      operation,
+      format: body.format || format,
+      filename: body.filename || filename,
+      sizeBytes: body.size_bytes || buffer.length,
+      sha256: body.sha256 || null,
+      artifactBase64: base64Data,
+      result: body.result || {},
+      durationMs,
+      logs: [
+        `[KERNEL] AgentSam CAD Docker Service (${url})`,
+        `[CONTAINER] Blender headless engine execution`,
+        ...(body.logs ? String(body.logs).split(/\r?\n/).filter(Boolean) : []),
+      ],
+    };
+  } catch (err) {
+    if (timer) clearTimeout(timer);
+    throw err;
+  }
+}

package/src/lib/cad/freecad.js

@@ -0,0 +1,253 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runProcess } from '../../security/process.js';
+import { discoverFreeCad, freeCadStatus } from './discovery.js';
+import { probeDockerServiceHealth, executeFreeCadDocker } from './docker-executor.js';
+
+const sdkRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+export const FREECAD_ADAPTER_PATH = path.join(sdkRoot, 'services/cad/freecad/adapter.py');
+export const FREECAD_RESULT_PREFIX = 'AGENTSAM_RESULT=';
+export const FREECAD_EXPORT_FORMATS = Object.freeze(['step', 'stp', 'iges', 'brep', 'stl']);
+
+function isFile(value) {
+  try {
+    return Boolean(value) && fs.existsSync(value) && fs.statSync(value).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Discovers the Python executable with FreeCAD / OpenCASCADE bindings.
+ */
+export function discoverFreeCadPython({
+  freecadBin,
+  env = process.env,
+  platform = process.platform,
+} = {}) {
+  // 1. Direct explicit environment override
+  if (env.AGENTSAM_FREECAD_PYTHON && isFile(env.AGENTSAM_FREECAD_PYTHON)) {
+    return {
+      pythonBin: env.AGENTSAM_FREECAD_PYTHON,
+      libDir: env.AGENTSAM_FREECAD_LIB || null,
+    };
+  }
+
+  // 2. Discover FreeCAD base installation
+  const { binary } = discoverFreeCad({ freecadBin, env, platform });
+  if (binary) {
+    if (platform === 'darwin') {
+      const appRoot = binary.includes('.app') ? binary.split('.app')[0] + '.app' : null;
+      if (appRoot) {
+        const bundledPython = path.join(appRoot, 'Contents/Resources/bin/python');
+        const bundledLib = path.join(appRoot, 'Contents/Resources/lib');
+        if (isFile(bundledPython)) {
+          return { pythonBin: bundledPython, libDir: bundledLib };
+        }
+      }
+    }
+  }
+
+  // 3. Fallback candidates on system
+  const candidates = [
+    ...(platform === 'darwin'
+      ? ['/Applications/FreeCAD.app/Contents/Resources/bin/python']
+      : []),
+    ...(platform === 'linux'
+      ? ['/usr/lib/freecad/bin/python', '/usr/bin/python3']
+      : []),
+    ...(platform === 'win32'
+      ? [path.join(env.ProgramFiles || 'C:\\Program Files', 'FreeCAD', 'bin', 'python.exe')]
+      : []),
+  ];
+
+  for (const c of candidates) {
+    if (isFile(c)) {
+      return { pythonBin: c, libDir: null };
+    }
+  }
+
+  return { pythonBin: null, libDir: null };
+}
+
+export function parseFreeCadResult(stdout) {
+  const line = String(stdout || '').split(/\r?\n/).reverse().find(value => value.startsWith(FREECAD_RESULT_PREFIX));
+  if (!line) throw new Error('FreeCAD did not return an AgentSam result envelope');
+  let value;
+  try {
+    value = JSON.parse(line.slice(FREECAD_RESULT_PREFIX.length));
+  } catch {
+    throw new Error('FreeCAD returned malformed AgentSam JSON');
+  }
+  if (!value || typeof value !== 'object') throw new Error('FreeCAD returned an invalid AgentSam result envelope');
+  return value;
+}
+
+/**
+ * Builds a precision boundary solid geometry with OpenCASCADE kernel and exports to STEP/IGES/BREP/STL.
+ */
+export async function freeCadBuild({
+  recipe,
+  output,
+  format = 'step',
+  freecadBin,
+  timeoutSeconds = 60,
+  cwd = process.cwd(),
+  runProcessImpl = runProcess,
+} = {}) {
+  const { pythonBin, libDir } = discoverFreeCadPython({ freecadBin });
+  if (!pythonBin || !fs.existsSync(FREECAD_ADAPTER_PATH)) {
+    try {
+      const dockerHealth = await probeDockerServiceHealth();
+      if (dockerHealth.available && dockerHealth.tools?.freecad?.installed) {
+        const dockerRes = await executeFreeCadDocker({
+          recipe,
+          operations: recipe?.operations || [],
+          format,
+          filename: output ? path.basename(output) : undefined,
+          timeoutMs: timeoutSeconds * 1000,
+        });
+        if (output) {
+          const outputPath = path.resolve(cwd, output);
+          fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+          fs.writeFileSync(outputPath, Buffer.from(dockerRes.artifactBase64, 'base64'));
+        }
+        return {
+          ...dockerRes,
+          engine: 'freecad-docker',
+        };
+      }
+    } catch {}
+    throw new Error('FreeCAD Python environment is not available; install FreeCAD, set AGENTSAM_FREECAD_PYTHON, or launch AgentSam CAD Docker service');
+  }
+
+  const outputPath = path.resolve(cwd, output);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+
+  const requestDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-freecad-'));
+  const requestPath = path.join(requestDir, 'request.json');
+
+  const request = {
+    schema_version: 1,
+    output: outputPath,
+    format,
+    operations: recipe?.operations || [],
+  };
+
+  fs.writeFileSync(requestPath, JSON.stringify(request, null, 2), { mode: 0o600 });
+
+  const env = { ...process.env };
+  if (libDir) {
+    env.PYTHONPATH = [libDir, env.PYTHONPATH].filter(Boolean).join(path.delimiter);
+  }
+
+  const started = Date.now();
+  try {
+    const proc = await runProcessImpl(
+      pythonBin,
+      [FREECAD_ADAPTER_PATH, '--operation', 'build', '--request', requestPath],
+      {
+        cwd,
+        env,
+        timeoutMs: timeoutSeconds * 1000,
+        maxBytes: 8 * 1024 * 1024,
+      }
+    );
+
+    const result = parseFreeCadResult(proc.stdout);
+    if (!result.ok) {
+      throw new Error(result.error || `FreeCAD build failed with exit code ${proc.code}`);
+    }
+
+    if (!fs.existsSync(outputPath)) {
+      throw new Error(`FreeCAD build did not create output file: ${outputPath}`);
+    }
+
+    const durationMs = Date.now() - started;
+    return {
+      schema_version: 1,
+      capability: 'freecad.build',
+      ok: true,
+      execution_lane: 'native',
+      format,
+      output: outputPath,
+      sizeBytes: fs.statSync(outputPath).size,
+      metrics: result.metrics,
+      durationMs,
+      logs: String(proc.stderr || proc.stdout || '').slice(-8000),
+    };
+  } finally {
+    fs.rmSync(requestDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Inspects a STEP / IGES / BREP solid model and returns exact geometric volume and bounding box.
+ */
+export async function freeCadInspect({
+  input,
+  freecadBin,
+  timeoutSeconds = 30,
+  cwd = process.cwd(),
+  runProcessImpl = runProcess,
+} = {}) {
+  const { pythonBin, libDir } = discoverFreeCadPython({ freecadBin });
+  if (!pythonBin) {
+    throw new Error('FreeCAD Python environment is not available');
+  }
+
+  const inputPath = path.resolve(cwd, input);
+  if (!fs.existsSync(inputPath)) {
+    throw new Error(`FreeCAD input file not found: ${inputPath}`);
+  }
+
+  const requestDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-freecad-inspect-'));
+  const requestPath = path.join(requestDir, 'request.json');
+
+  const request = {
+    schema_version: 1,
+    input: inputPath,
+  };
+
+  fs.writeFileSync(requestPath, JSON.stringify(request, null, 2), { mode: 0o600 });
+
+  const env = { ...process.env };
+  if (libDir) {
+    env.PYTHONPATH = [libDir, env.PYTHONPATH].filter(Boolean).join(path.delimiter);
+  }
+
+  const started = Date.now();
+  try {
+    const proc = await runProcessImpl(
+      pythonBin,
+      [FREECAD_ADAPTER_PATH, '--operation', 'inspect', '--request', requestPath],
+      {
+        cwd,
+        env,
+        timeoutMs: timeoutSeconds * 1000,
+        maxBytes: 8 * 1024 * 1024,
+      }
+    );
+
+    const result = parseFreeCadResult(proc.stdout);
+    if (!result.ok) {
+      throw new Error(result.error || `FreeCAD inspect failed with exit code ${proc.code}`);
+    }
+
+    return {
+      schema_version: 1,
+      capability: 'freecad.inspect',
+      ok: true,
+      execution_lane: 'native',
+      input: inputPath,
+      metrics: result.metrics,
+      durationMs: Date.now() - started,
+    };
+  } finally {
+    fs.rmSync(requestDir, { recursive: true, force: true });
+  }
+}
+
+export { freeCadStatus };

package/src/lib/cad/index.js

@@ -13,3 +13,43 @@ export {
   sha256File,
   validateBlenderRecipe,
 } from './blender.js';
+
+export {
+  discoverOpenScad,
+  openScadStatus,
+  discoverFreeCad,
+  freeCadStatus,
+  meshyStatus,
+  mujocoStatus,
+  discoverAllCadTools,
+  getCadConfigPath,
+  loadCadConfig,
+  saveCadConfig,
+  getInstallGuidance,
+} from './discovery.js';
+
+export {
+  openScadCompile,
+  validateOpenScadSource,
+  FORBIDDEN_OPENSCAD_PATTERNS,
+} from './openscad.js';
+
+export {
+  FREECAD_ADAPTER_PATH,
+  FREECAD_EXPORT_FORMATS,
+  discoverFreeCadPython,
+  freeCadBuild,
+  freeCadInspect,
+} from './freecad.js';
+
+export {
+  DEFAULT_CAD_DOCKER_PORT,
+  DEFAULT_CAD_DOCKER_URL,
+  resolveDockerServiceConfig,
+  probeDockerServiceHealth,
+  executeOpenScadDocker,
+  executeFreeCadDocker,
+  executeBlenderDocker,
+} from './docker-executor.js';
+
+