@inneranimalmedia/agentsam-sdk 2.2.1 → 2.4.0

package/src/commands/cad.js

@@ -0,0 +1,138 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  blenderBuild,
+  blenderExport,
+  blenderInspect,
+  blenderRenderPreview,
+  blenderStatus,
+} from '../lib/cad/index.js';
+
+function usage() {
+  return `AgentSam programmatic CAD
+
+Usage:
+  agentsam cad blender status [--blender-bin <path>] [--json]
+  agentsam cad blender inspect <model.blend> [--timeout <seconds>] [--json]
+  agentsam cad blender build <recipe.json> --out <model.blend> [--input <base.blend>] [--json]
+  agentsam cad blender render-preview <model.blend> --out <preview.png> [--camera <name>] [--scene <name>] [--width 1024] [--height 1024] [--json]
+  agentsam cad blender export <model.blend> --format <glb|stl|obj> --out <artifact> [--objects <a,b>] [--collection <name>] [--json]
+
+Shared options:
+  --blender-bin <path>  Explicit Blender executable. Otherwise AGENTSAM_BLENDER_BIN, PATH, then common install locations are checked.
+  --timeout <seconds>   Bounded execution time, 1..600 (default 120).
+  --cwd <path>          Resolve input/output paths from another directory.
+  --json                Machine-readable output.
+
+The build command consumes a typed recipe; it never evaluates arbitrary Python.`;
+}
+
+function parseArgs(argv) {
+  const opts = { positional: [], json: false, applyModifiers: true };
+  const values = new Set([
+    '--blender-bin', '--timeout', '--cwd', '--out', '--input', '--camera', '--scene',
+    '--width', '--height', '--engine', '--format', '--objects', '--collection',
+  ]);
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') opts.json = true;
+    else if (arg === '--no-apply-modifiers') opts.applyModifiers = false;
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (values.has(arg)) {
+      const value = argv[++i];
+      if (value == null || value.startsWith('--')) throw new Error(`${arg} requires a value`);
+      const key = arg.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+      opts[key] = value;
+    } else if (arg.startsWith('-')) throw new Error(`unknown cad option: ${arg}`);
+    else opts.positional.push(arg);
+  }
+  return opts;
+}
+
+function output(value, json) {
+  if (json) {
+    console.log(JSON.stringify(value));
+    return;
+  }
+  if (value.capability === 'blender.status') {
+    console.log(value.available
+      ? `Blender available: ${value.version || 'unknown version'}\n${value.binary}`
+      : `Blender unavailable${value.error ? `: ${value.error}` : ''}`);
+    return;
+  }
+  console.log(JSON.stringify(value, null, 2));
+}
+
+function required(value, message) {
+  if (!value) throw new Error(message);
+  return value;
+}
+
+export async function runCad(argv) {
+  const engine = argv[0];
+  if (!engine || engine === '--help' || engine === '-h') {
+    console.log(usage());
+    return;
+  }
+  if (engine !== 'blender') throw new Error(`unsupported CAD engine: ${engine}. Expected blender.`);
+
+  const action = argv[1];
+  const opts = parseArgs(argv.slice(2));
+  if (!action || opts.help) {
+    console.log(usage());
+    return;
+  }
+
+  const cwd = path.resolve(opts.cwd || process.cwd());
+  const shared = {
+    blenderBin: opts.blenderBin,
+    timeoutSeconds: opts.timeout == null ? undefined : Number(opts.timeout),
+    cwd,
+  };
+
+  let result;
+  if (action === 'status') {
+    result = await blenderStatus(shared);
+  } else if (action === 'inspect') {
+    result = await blenderInspect({ ...shared, input: required(opts.positional[0], 'inspect requires <model.blend>') });
+  } else if (action === 'build') {
+    const recipeFile = path.resolve(cwd, required(opts.positional[0], 'build requires <recipe.json>'));
+    if (!fs.existsSync(recipeFile)) throw new Error(`recipe file not found: ${recipeFile}`);
+    let recipe;
+    try { recipe = JSON.parse(fs.readFileSync(recipeFile, 'utf8')); }
+    catch (error) { throw new Error(`invalid recipe JSON: ${error.message}`); }
+    result = await blenderBuild({
+      ...shared,
+      input: opts.input,
+      output: required(opts.out, 'build requires --out <model.blend>'),
+      recipe,
+    });
+  } else if (action === 'render-preview') {
+    result = await blenderRenderPreview({
+      ...shared,
+      input: required(opts.positional[0], 'render-preview requires <model.blend>'),
+      output: required(opts.out, 'render-preview requires --out <preview.png>'),
+      scene: opts.scene,
+      camera: opts.camera,
+      width: opts.width == null ? undefined : Number(opts.width),
+      height: opts.height == null ? undefined : Number(opts.height),
+      engine: opts.engine,
+    });
+  } else if (action === 'export') {
+    result = await blenderExport({
+      ...shared,
+      input: required(opts.positional[0], 'export requires <model.blend>'),
+      output: required(opts.out, 'export requires --out <artifact>'),
+      format: required(opts.format, 'export requires --format <glb|stl|obj>'),
+      scene: opts.scene,
+      objects: opts.objects,
+      collection: opts.collection,
+      applyModifiers: opts.applyModifiers,
+    });
+  } else {
+    throw new Error(`unknown Blender CAD action: ${action}`);
+  }
+
+  output(result, opts.json);
+  return result;
+}

package/src/lib/cad/blender.js

@@ -0,0 +1,340 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { runProcess } from '../../security/process.js';
+
+const sdkRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+export const BLENDER_ADAPTER_PATH = path.join(sdkRoot, 'services/cad/blender/adapter.py');
+export const BLENDER_RESULT_PREFIX = 'AGENTSAM_RESULT=';
+export const BLENDER_EXPORT_FORMATS = Object.freeze(['glb', 'stl', 'obj']);
+export const BLENDER_RECIPE_OPS = Object.freeze([
+  'clear_scene',
+  'add',
+  'transform',
+  'duplicate',
+  'delete',
+  'join',
+  'bevel',
+  'solidify',
+  'array',
+  'mirror',
+  'boolean',
+  'material',
+  'assign_material',
+  'add_camera',
+  'add_light',
+]);
+
+function isFile(value, existsSync = fs.existsSync) {
+  try { return Boolean(value) && existsSync(value) && fs.statSync(value).isFile(); }
+  catch { return false; }
+}
+
+function canonicalExecutable(value) {
+  try { return fs.realpathSync.native ? fs.realpathSync.native(value) : fs.realpathSync(value); }
+  catch { return value; }
+}
+
+function pathCandidates(pathEnv, platform) {
+  const names = platform === 'win32' ? ['blender.exe', 'blender'] : ['blender'];
+  return String(pathEnv || '')
+    .split(path.delimiter)
+    .filter(Boolean)
+    .flatMap(dir => names.map(name => path.join(dir, name)));
+}
+
+function windowsInstallCandidates(env = process.env, readdirSync = fs.readdirSync) {
+  const roots = [env.ProgramFiles, env['ProgramFiles(x86)'], env.LOCALAPPDATA]
+    .filter(Boolean)
+    .flatMap(root => [
+      path.join(root, 'Blender Foundation'),
+      path.join(root, 'Programs', 'Blender Foundation'),
+    ]);
+  const found = [];
+  for (const root of roots) {
+    try {
+      const entries = readdirSync(root, { withFileTypes: true })
+        .filter(entry => entry.isDirectory() && /^Blender(?:\s|$)/i.test(entry.name))
+        .sort((a, b) => b.name.localeCompare(a.name, undefined, { numeric: true }));
+      for (const entry of entries) found.push(path.join(root, entry.name, 'blender.exe'));
+      found.push(path.join(root, 'blender.exe'));
+    } catch { /* optional search root */ }
+  }
+  return found;
+}
+
+export function discoverBlender({
+  blenderBin,
+  env = process.env,
+  platform = process.platform,
+  existsSync = fs.existsSync,
+  readdirSync = fs.readdirSync,
+} = {}) {
+  const explicit = String(blenderBin || '').trim();
+  if (explicit) {
+    const resolved = path.resolve(explicit);
+    if (!isFile(resolved, existsSync)) throw new Error(`Blender binary not found: ${resolved}`);
+    return canonicalExecutable(resolved);
+  }
+
+  const configured = String(env.AGENTSAM_BLENDER_BIN || '').trim();
+  if (configured) {
+    const resolved = path.resolve(configured);
+    if (!isFile(resolved, existsSync)) throw new Error(`AGENTSAM_BLENDER_BIN does not exist: ${resolved}`);
+    return canonicalExecutable(resolved);
+  }
+
+  const candidates = [
+    ...pathCandidates(env.PATH, platform),
+    ...(platform === 'win32' ? windowsInstallCandidates(env, readdirSync) : []),
+    ...(platform === 'darwin' ? ['/Applications/Blender.app/Contents/MacOS/Blender'] : []),
+    ...(platform === 'linux' ? ['/usr/bin/blender', '/usr/local/bin/blender', '/snap/bin/blender'] : []),
+  ];
+  const found = candidates.find(candidate => isFile(candidate, existsSync));
+  return found ? canonicalExecutable(found) : null;
+}
+
+export function sha256File(file) {
+  const hash = createHash('sha256');
+  hash.update(fs.readFileSync(file));
+  return hash.digest('hex');
+}
+
+function boundedInteger(value, fallback, min, max, label) {
+  const parsed = value == null ? fallback : Number(value);
+  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+    throw new Error(`${label} must be an integer from ${min} to ${max}`);
+  }
+  return parsed;
+}
+
+function resolveInputBlend(input, cwd = process.cwd()) {
+  const resolved = path.resolve(cwd, String(input || ''));
+  if (!String(input || '').trim()) throw new Error('Blender input file is required');
+  if (path.extname(resolved).toLowerCase() !== '.blend') throw new Error('Blender input must be a .blend file');
+  if (!isFile(resolved)) throw new Error(`Blender input file not found: ${resolved}`);
+  return resolved;
+}
+
+function resolveOutput(output, expectedExt, cwd = process.cwd(), input = null) {
+  if (!String(output || '').trim()) throw new Error('Output path is required');
+  const resolved = path.resolve(cwd, output);
+  if (path.extname(resolved).toLowerCase() !== expectedExt) {
+    throw new Error(`Output must end in ${expectedExt}`);
+  }
+  if (input && path.resolve(input) === resolved) throw new Error('Blender operations never overwrite the source .blend file');
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  return resolved;
+}
+
+export function validateBlenderRecipe(recipe) {
+  if (!recipe || typeof recipe !== 'object' || Array.isArray(recipe)) throw new Error('Blender recipe must be a JSON object');
+  if (recipe.schema_version !== 1) throw new Error('Blender recipe schema_version must be 1');
+  if (!Array.isArray(recipe.operations) || recipe.operations.length < 1) throw new Error('Blender recipe operations must be a non-empty array');
+  if (recipe.operations.length > 256) throw new Error('Blender recipe may contain at most 256 operations');
+  for (let index = 0; index < recipe.operations.length; index += 1) {
+    const operation = recipe.operations[index];
+    if (!operation || typeof operation !== 'object' || Array.isArray(operation)) throw new Error(`recipe operation ${index} must be an object`);
+    const op = String(operation.op || '').trim();
+    if (!BLENDER_RECIPE_OPS.includes(op)) throw new Error(`unsupported Blender recipe operation at ${index}: ${op || '<empty>'}`);
+  }
+  return structuredClone(recipe);
+}
+
+export function parseBlenderResult(stdout) {
+  const line = String(stdout || '').split(/\r?\n/).reverse().find(value => value.startsWith(BLENDER_RESULT_PREFIX));
+  if (!line) throw new Error('Blender did not return an AgentSam result envelope');
+  let value;
+  try { value = JSON.parse(line.slice(BLENDER_RESULT_PREFIX.length)); }
+  catch { throw new Error('Blender returned malformed AgentSam JSON'); }
+  if (!value || typeof value !== 'object') throw new Error('Blender returned an invalid AgentSam result envelope');
+  return value;
+}
+
+export function createBlenderInvocation({ operation, input, requestPath, blenderBin, factoryStartup = false }) {
+  const args = ['--background'];
+  if (factoryStartup) args.push('--factory-startup');
+  if (input) args.push(input);
+  args.push('--python', BLENDER_ADAPTER_PATH, '--', '--operation', operation, '--request', requestPath);
+  return { command: blenderBin, args };
+}
+
+async function invokeBlender({
+  operation,
+  input = null,
+  request = {},
+  blenderBin,
+  timeoutSeconds = 120,
+  cwd = process.cwd(),
+  factoryStartup = false,
+  runProcessImpl = runProcess,
+}) {
+  const binary = discoverBlender({ blenderBin });
+  if (!binary) throw new Error('Blender is not installed or could not be discovered; use --blender-bin or AGENTSAM_BLENDER_BIN');
+  if (!fs.existsSync(BLENDER_ADAPTER_PATH)) throw new Error(`Bundled Blender adapter is missing: ${BLENDER_ADAPTER_PATH}`);
+  const timeout = boundedInteger(timeoutSeconds, 120, 1, 600, 'timeout');
+  const requestDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-blender-'));
+  const requestPath = path.join(requestDir, 'request.json');
+  fs.writeFileSync(requestPath, JSON.stringify({ schema_version: 1, ...request }, null, 2), { mode: 0o600 });
+  const invocation = createBlenderInvocation({ operation, input, requestPath, blenderBin: binary, factoryStartup });
+  const started = Date.now();
+  try {
+    const proc = await runProcessImpl(invocation.command, invocation.args, {
+      cwd,
+      timeoutMs: timeout * 1000,
+      maxBytes: 4 * 1024 * 1024,
+    });
+    let result;
+    try { result = parseBlenderResult(proc.stdout); }
+    catch (error) {
+      if (proc.code !== 0) throw new Error(`Blender ${operation} failed with exit ${proc.code}: ${(proc.stderr || proc.stdout || '').slice(-4000)}`);
+      throw error;
+    }
+    if (proc.code !== 0 || result.ok === false) throw new Error(result.error || `Blender ${operation} failed with exit ${proc.code}`);
+    return {
+      result,
+      binary,
+      duration_ms: Date.now() - started,
+      logs: String(proc.stderr || '').slice(-8000),
+    };
+  } finally {
+    fs.rmSync(requestDir, { recursive: true, force: true });
+  }
+}
+
+export async function blenderStatus({ blenderBin, runProcessImpl = runProcess } = {}) {
+  let binary;
+  try { binary = discoverBlender({ blenderBin }); }
+  catch (error) {
+    return { schema_version: 1, capability: 'blender.status', available: false, binary: null, version: null, execution_lane: 'native', error: error.message };
+  }
+  if (!binary) return { schema_version: 1, capability: 'blender.status', available: false, binary: null, version: null, execution_lane: 'native' };
+  const proc = await runProcessImpl(binary, ['--version'], { timeoutMs: 10_000, maxBytes: 256 * 1024 });
+  const version = String(proc.stdout || proc.stderr || '').split(/\r?\n/).find(Boolean)?.trim() || null;
+  return { schema_version: 1, capability: 'blender.status', available: proc.code === 0, binary, version, execution_lane: 'native' };
+}
+
+function inputReceipt(input) {
+  return input ? { path: input, sha256: sha256File(input) } : null;
+}
+
+function artifactReceipt(file, format) {
+  const stat = fs.statSync(file);
+  return { path: file, format, size_bytes: stat.size, sha256: sha256File(file) };
+}
+
+export async function blenderInspect({ input, blenderBin, timeoutSeconds, cwd = process.cwd(), runProcessImpl } = {}) {
+  const source = resolveInputBlend(input, cwd);
+  const inputInfo = inputReceipt(source);
+  const run = await invokeBlender({ operation: 'inspect', input: source, blenderBin, timeoutSeconds, cwd, runProcessImpl });
+  return {
+    schema_version: 1,
+    capability: 'blender.inspect',
+    ok: true,
+    execution_lane: 'native',
+    input: inputInfo,
+    blender: { binary: run.binary, version: run.result.blender_version || null },
+    scene: run.result.scene,
+    duration_ms: run.duration_ms,
+    warnings: run.result.warnings || [],
+  };
+}
+
+export async function blenderBuild({ input, output, recipe, blenderBin, timeoutSeconds, cwd = process.cwd(), runProcessImpl } = {}) {
+  const source = input ? resolveInputBlend(input, cwd) : null;
+  const target = resolveOutput(output, '.blend', cwd, source);
+  const normalizedRecipe = validateBlenderRecipe(recipe);
+  const run = await invokeBlender({
+    operation: 'build',
+    input: source,
+    request: { output: target, recipe: normalizedRecipe },
+    blenderBin,
+    timeoutSeconds,
+    cwd,
+    factoryStartup: !source,
+    runProcessImpl,
+  });
+  if (!isFile(target)) throw new Error(`Blender build did not create output: ${target}`);
+  return {
+    schema_version: 1,
+    capability: 'blender.build',
+    ok: true,
+    execution_lane: 'native',
+    input: inputReceipt(source),
+    blender: { binary: run.binary, version: run.result.blender_version || null },
+    artifact: artifactReceipt(target, 'blend'),
+    operations_applied: run.result.operations_applied ?? normalizedRecipe.operations.length,
+    objects: run.result.objects || [],
+    duration_ms: run.duration_ms,
+    warnings: run.result.warnings || [],
+  };
+}
+
+export async function blenderRenderPreview({ input, output, scene, camera, width = 1024, height = 1024, engine, blenderBin, timeoutSeconds, cwd = process.cwd(), runProcessImpl } = {}) {
+  const source = resolveInputBlend(input, cwd);
+  const target = resolveOutput(output, '.png', cwd, source);
+  const request = {
+    output: target,
+    scene: scene || null,
+    camera: camera || null,
+    width: boundedInteger(width, 1024, 64, 4096, 'width'),
+    height: boundedInteger(height, 1024, 64, 4096, 'height'),
+    engine: engine || null,
+  };
+  const run = await invokeBlender({ operation: 'render_preview', input: source, request, blenderBin, timeoutSeconds, cwd, runProcessImpl });
+  if (!isFile(target)) throw new Error(`Blender render did not create output: ${target}`);
+  return {
+    schema_version: 1,
+    capability: 'blender.render_preview',
+    ok: true,
+    execution_lane: 'native',
+    input: inputReceipt(source),
+    blender: { binary: run.binary, version: run.result.blender_version || null },
+    artifact: artifactReceipt(target, 'png'),
+    scene: run.result.scene || null,
+    camera: run.result.camera || null,
+    duration_ms: run.duration_ms,
+    warnings: run.result.warnings || [],
+  };
+}
+
+export async function blenderExport({ input, output, format, scene, objects, collection, applyModifiers = true, blenderBin, timeoutSeconds, cwd = process.cwd(), runProcessImpl } = {}) {
+  const source = resolveInputBlend(input, cwd);
+  const normalizedFormat = String(format || '').toLowerCase().replace(/^\./, '');
+  if (!BLENDER_EXPORT_FORMATS.includes(normalizedFormat)) throw new Error(`Unsupported Blender export format: ${normalizedFormat || '<empty>'}. Expected ${BLENDER_EXPORT_FORMATS.join(', ')}`);
+  const target = resolveOutput(output, `.${normalizedFormat}`, cwd, source);
+  const selectedObjects = Array.isArray(objects)
+    ? objects.map(String).filter(Boolean)
+    : String(objects || '').split(',').map(value => value.trim()).filter(Boolean);
+  const run = await invokeBlender({
+    operation: 'export',
+    input: source,
+    request: {
+      output: target,
+      format: normalizedFormat,
+      scene: scene || null,
+      objects: selectedObjects,
+      collection: collection || null,
+      apply_modifiers: Boolean(applyModifiers),
+    },
+    blenderBin,
+    timeoutSeconds,
+    cwd,
+    runProcessImpl,
+  });
+  if (!isFile(target)) throw new Error(`Blender export did not create output: ${target}`);
+  return {
+    schema_version: 1,
+    capability: 'blender.export',
+    ok: true,
+    execution_lane: 'native',
+    input: inputReceipt(source),
+    blender: { binary: run.binary, version: run.result.blender_version || null },
+    artifact: artifactReceipt(target, normalizedFormat),
+    selected_objects: run.result.selected_objects || [],
+    duration_ms: run.duration_ms,
+    warnings: run.result.warnings || [],
+  };
+}

package/src/lib/cad/index.js

@@ -0,0 +1,15 @@
+export {
+  BLENDER_ADAPTER_PATH,
+  BLENDER_EXPORT_FORMATS,
+  BLENDER_RECIPE_OPS,
+  blenderBuild,
+  blenderExport,
+  blenderInspect,
+  blenderRenderPreview,
+  blenderStatus,
+  createBlenderInvocation,
+  discoverBlender,
+  parseBlenderResult,
+  sha256File,
+  validateBlenderRecipe,
+} from './blender.js';

package/test/blender-cad.test.mjs

@@ -0,0 +1,146 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  BLENDER_ADAPTER_PATH,
+  blenderBuild,
+  blenderInspect,
+  blenderStatus,
+  createBlenderInvocation,
+  discoverBlender,
+  parseBlenderResult,
+  validateBlenderRecipe,
+} from '../src/lib/cad/index.js';
+
+function fixture(t) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-blender-test-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const binary = path.join(root, process.platform === 'win32' ? 'blender.exe' : 'blender');
+  fs.writeFileSync(binary, 'fake blender\n');
+  const blend = path.join(root, 'source.blend');
+  fs.writeFileSync(blend, 'blend fixture\n');
+  return { root, binary, blend };
+}
+
+function resultEnvelope(value) {
+  return { code: 0, stdout: `Blender startup noise\nAGENTSAM_RESULT=${JSON.stringify(value)}\n`, stderr: '' };
+}
+
+test('Blender adapter is packaged at the SDK-owned fixed path', () => {
+  assert.equal(path.basename(BLENDER_ADAPTER_PATH), 'adapter.py');
+  assert.ok(fs.existsSync(BLENDER_ADAPTER_PATH));
+});
+
+test('discoverBlender honors explicit binary before environment discovery', t => {
+  const { binary } = fixture(t);
+  assert.equal(discoverBlender({ blenderBin: binary, env: { AGENTSAM_BLENDER_BIN: '/wrong' } }), fs.realpathSync(binary));
+  assert.throws(() => discoverBlender({ blenderBin: path.join(path.dirname(binary), 'missing') }), /not found/);
+});
+
+test('Blender status uses argv execution and returns version without shell parsing', async t => {
+  const { binary } = fixture(t);
+  const calls = [];
+  const result = await blenderStatus({
+    blenderBin: binary,
+    runProcessImpl: async (command, args) => {
+      calls.push({ command, args });
+      return { code: 0, stdout: 'Blender 4.5.3 LTS\n', stderr: '' };
+    },
+  });
+  assert.equal(result.available, true);
+  assert.equal(result.version, 'Blender 4.5.3 LTS');
+  assert.deepEqual(calls, [{ command: fs.realpathSync(binary), args: ['--version'] }]);
+});
+
+test('typed Blender recipe rejects arbitrary or unknown operations', () => {
+  const valid = validateBlenderRecipe({
+    schema_version: 1,
+    operations: [
+      { op: 'add', primitive: 'cube', name: 'Body', size: 20 },
+      { op: 'bevel', object: 'Body', width: 1, segments: 3 },
+    ],
+  });
+  assert.equal(valid.operations.length, 2);
+  assert.throws(() => validateBlenderRecipe({ schema_version: 1, operations: [{ op: 'python', code: 'import bpy' }] }), /unsupported Blender recipe operation/);
+});
+
+test('Blender invocation is background + fixed adapter + typed request, never shell code', t => {
+  const { binary, blend, root } = fixture(t);
+  const requestPath = path.join(root, 'request.json');
+  const value = createBlenderInvocation({ operation: 'inspect', input: blend, requestPath, blenderBin: binary });
+  assert.equal(value.command, binary);
+  assert.deepEqual(value.args.slice(0, 2), ['--background', blend]);
+  assert.ok(value.args.includes('--python'));
+  assert.ok(value.args.includes(BLENDER_ADAPTER_PATH));
+  assert.deepEqual(value.args.slice(-4), ['--operation', 'inspect', '--request', requestPath]);
+});
+
+test('parseBlenderResult ignores Blender logs and reads the machine envelope', () => {
+  assert.deepEqual(parseBlenderResult('noise\nAGENTSAM_RESULT={"ok":true,"value":7}\n'), { ok: true, value: 7 });
+  assert.throws(() => parseBlenderResult('noise only'), /did not return/);
+});
+
+test('blenderInspect returns source hash and scene evidence without writing source', async t => {
+  const { binary, blend } = fixture(t);
+  const before = fs.readFileSync(blend, 'utf8');
+  const result = await blenderInspect({
+    input: blend,
+    blenderBin: binary,
+    runProcessImpl: async () => resultEnvelope({
+      ok: true,
+      blender_version: '4.5.3',
+      scene: { active: 'Scene', objects: [{ name: 'Body', type: 'MESH' }] },
+      warnings: [],
+    }),
+  });
+  assert.equal(result.capability, 'blender.inspect');
+  assert.equal(result.scene.objects[0].name, 'Body');
+  assert.match(result.input.sha256, /^[a-f0-9]{64}$/);
+  assert.equal(fs.readFileSync(blend, 'utf8'), before);
+});
+
+test('blenderBuild executes a bounded recipe and produces a hashed .blend artifact', async t => {
+  const { binary, root } = fixture(t);
+  const output = path.join(root, 'built.blend');
+  const recipe = {
+    schema_version: 1,
+    units: { system: 'METRIC', scale_length: 0.001, length_unit: 'MILLIMETERS' },
+    operations: [
+      { op: 'clear_scene' },
+      { op: 'add', primitive: 'cube', name: 'Body', size: 20 },
+      { op: 'add', primitive: 'cylinder', name: 'Hole', radius: 3, depth: 30 },
+      { op: 'boolean', object: 'Body', with: 'Hole', operation: 'DIFFERENCE', delete_operand: true },
+    ],
+  };
+  let seenRequest;
+  const result = await blenderBuild({
+    output,
+    recipe,
+    blenderBin: binary,
+    runProcessImpl: async (_command, args) => {
+      const requestPath = args[args.indexOf('--request') + 1];
+      seenRequest = JSON.parse(fs.readFileSync(requestPath, 'utf8'));
+      fs.writeFileSync(seenRequest.output, 'generated blend artifact\n');
+      return resultEnvelope({ ok: true, blender_version: '4.5.3', operations_applied: recipe.operations.length, objects: ['Body'], warnings: [] });
+    },
+  });
+  assert.equal(seenRequest.recipe.operations[3].operation, 'DIFFERENCE');
+  assert.equal(result.capability, 'blender.build');
+  assert.equal(result.artifact.path, output);
+  assert.equal(result.artifact.format, 'blend');
+  assert.match(result.artifact.sha256, /^[a-f0-9]{64}$/);
+  assert.deepEqual(result.objects, ['Body']);
+});
+
+test('Blender build refuses to overwrite an input source .blend', async t => {
+  const { binary, blend } = fixture(t);
+  await assert.rejects(() => blenderBuild({
+    input: blend,
+    output: blend,
+    blenderBin: binary,
+    recipe: { schema_version: 1, operations: [{ op: 'clear_scene' }] },
+    runProcessImpl: async () => { throw new Error('runner should not execute'); },
+  }), /never overwrite/);
+});