@inneranimalmedia/agentsam-sdk 2.3.0 → 2.4.1

package/src/commands/cad.js

@@ -0,0 +1,188 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  blenderBuild,
+  blenderExport,
+  blenderInspect,
+  blenderRenderPreview,
+  blenderStatus,
+} from '../lib/cad/index.js';
+import { promptToOpenUrl } from '../lib/open-url.js';
+
+const BLENDER_DOWNLOAD_URL = 'https://www.blender.org/download/';
+
+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.
+
+If Blender is missing, AgentSam explains what is required and can open the official Blender download page.
+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 withBlenderInstallGuidance(value) {
+  if (value?.available !== false) return value;
+  return {
+    ...value,
+    install: {
+      required: true,
+      app: 'Blender',
+      url: BLENDER_DOWNLOAD_URL,
+      message: 'Install Blender, then rerun this command. AgentSam will discover standard installs automatically.',
+      alternatives: [
+        'Pass --blender-bin <path> for a custom Blender executable.',
+        'Set AGENTSAM_BLENDER_BIN for a persistent custom executable path.',
+      ],
+    },
+  };
+}
+
+function output(value, json) {
+  if (json) {
+    console.log(JSON.stringify(value));
+    return;
+  }
+  if (value.capability === 'blender.status') {
+    if (value.available) {
+      console.log(`Blender available: ${value.version || 'unknown version'}\n${value.binary}`);
+    } else {
+      console.log(`Blender unavailable${value.error ? `: ${value.error}` : ''}`);
+      if (value.install?.message) console.log(value.install.message);
+      if (value.install?.url) console.log(`Download: ${value.install.url}`);
+    }
+    return;
+  }
+  console.log(JSON.stringify(value, null, 2));
+}
+
+async function presentMissingBlender(value, json) {
+  const guided = withBlenderInstallGuidance(value);
+  output(guided, json);
+  if (!json) {
+    await promptToOpenUrl(BLENDER_DOWNLOAD_URL, {
+      heading: 'Blender is required for AgentSam programmatic CAD:',
+      prompt: 'Press ENTER to open the official Blender download page.',
+    });
+  }
+  return guided;
+}
+
+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,
+  };
+
+  if (action === 'status') {
+    const status = withBlenderInstallGuidance(await blenderStatus(shared));
+    output(status, opts.json);
+    if (!status.available && !opts.json) {
+      await promptToOpenUrl(BLENDER_DOWNLOAD_URL, {
+        heading: 'Install Blender to enable AgentSam CAD:',
+        prompt: 'Press ENTER to open the official Blender download page.',
+      });
+    }
+    return status;
+  }
+
+  const availability = await blenderStatus(shared);
+  if (!availability.available) return presentMissingBlender(availability, opts.json);
+
+  let result;
+  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/auth.js

@@ -1,28 +1,15 @@
 /**
  * Browser OAuth for SDK init — one click IAM login + Cloudflare connect.
  */
-import http from 'http';
-import { randomBytes } from 'crypto';
+import http from 'node:http';
+import { randomBytes } from 'node:crypto';
 import { postJson } from './core-client.js';
+import { promptToOpenUrl } from './open-url.js';
 
 function randomState() {
   return randomBytes(16).toString('hex');
 }
 
-function openBrowser(url) {
-  const start =
-    process.platform === 'darwin'
-      ? ['open', url]
-      : process.platform === 'win32'
-        ? ['cmd', '/c', 'start', '', url]
-        : ['xdg-open', url];
-  import('child_process').then(({ spawn }) => {
-    spawn(start[0], start.slice(1), { stdio: 'ignore', detached: true }).unref();
-  }).catch(() => {
-    console.log(`\n  Open in browser:\n  ${url}\n`);
-  });
-}
-
 /**
  * @returns {Promise<{ access_token: string, user_id: string, workspace_id: string, tenant_id: string }>}
  */
@@ -36,6 +23,8 @@ export async function authenticateViaBrowser() {
     state,
   });
 
+  if (!authUrl) throw new Error('IAM auth did not return an authorization URL');
+
   const codePromise = new Promise((resolve, reject) => {
     const server = http.createServer((req, res) => {
       try {
@@ -55,7 +44,7 @@ export async function authenticateViaBrowser() {
           return;
         }
         res.writeHead(200, { 'Content-Type': 'text/html' });
-        res.end('<html><body style="font-family:system-ui"><h1>Agent Sam</h1><p>You can close this tab.</p></body></html>');
+        res.end('<html><body style="font-family:system-ui"><h1>Agent Sam</h1><p>Authentication complete. You can close this tab and return to your terminal.</p></body></html>');
         resolve(code);
         server.close();
       } catch (e) {
@@ -67,8 +56,10 @@ export async function authenticateViaBrowser() {
     server.listen(port, '127.0.0.1');
   });
 
-  console.log('\n  Opening browser for IAM sign-in + Cloudflare connect…\n');
-  openBrowser(authUrl);
+  await promptToOpenUrl(authUrl, {
+    heading: 'Authenticate your InnerAnimalMedia account at:',
+    prompt: 'Press ENTER to open InnerAnimalMedia sign-in in your browser.',
+  });
 
   const code = await codePromise;
   const session = await postJson('/api/sdk/auth/exchange', { code, state });

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/src/lib/open-url.js

@@ -0,0 +1,66 @@
+import readline from 'node:readline';
+import { spawn } from 'node:child_process';
+
+function normalizeHttpUrl(value) {
+  const raw = String(value || '').trim();
+  if (!raw) throw new Error('URL is required');
+  let parsed;
+  try { parsed = new URL(raw); }
+  catch { throw new Error(`Invalid URL: ${raw}`); }
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error(`Unsupported URL protocol: ${parsed.protocol}`);
+  }
+  return parsed.toString();
+}
+
+export function browserCommand(url, platform = process.platform) {
+  const normalized = normalizeHttpUrl(url);
+  if (platform === 'darwin') return { command: 'open', args: [normalized] };
+  if (platform === 'win32') return { command: 'cmd', args: ['/c', 'start', '', normalized] };
+  return { command: 'xdg-open', args: [normalized] };
+}
+
+export function openExternalUrl(url, {
+  platform = process.platform,
+  spawnImpl = spawn,
+} = {}) {
+  const invocation = browserCommand(url, platform);
+  const child = spawnImpl(invocation.command, invocation.args, {
+    stdio: 'ignore',
+    detached: true,
+  });
+  child.unref?.();
+  return invocation;
+}
+
+export async function promptToOpenUrl(url, {
+  heading = 'Open in your browser:',
+  prompt = 'Press ENTER to open in the browser, or copy the URL above.',
+  input = process.stdin,
+  output = process.stdout,
+  openImpl = openExternalUrl,
+} = {}) {
+  const normalized = normalizeHttpUrl(url);
+  output.write(`\n${heading}\n${normalized}\n`);
+
+  if (!input?.isTTY || !output?.isTTY) {
+    output.write('Open the URL above in a browser to continue.\n\n');
+    return { url: normalized, opened: false, interactive: false };
+  }
+
+  const rl = readline.createInterface({ input, output });
+  try {
+    await new Promise(resolve => rl.question(`\n${prompt}\n`, resolve));
+  } finally {
+    rl.close();
+  }
+
+  try {
+    openImpl(normalized);
+    output.write('\nBrowser opened. Complete the step there, then return here.\n\n');
+    return { url: normalized, opened: true, interactive: true };
+  } catch (error) {
+    output.write(`\nCould not open the browser automatically: ${error.message}\nOpen the URL above manually.\n\n`);
+    return { url: normalized, opened: false, interactive: true, error: error.message };
+  }
+}