@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.3

package/src/knowledge/service/job-engine.js

@@ -5,23 +5,83 @@ import { fork } from 'node:child_process';
 import { DatabaseSync } from 'node:sqlite';
 import { fileURLToPath } from 'node:url';
 import { fingerprint, validateConfig } from '../config.js';
+import {
+  AgentSamError,
+  ERROR_CODE,
+  ERROR_REASON,
+  createErrorEnvelope,
+  normalizeError,
+  parseError,
+} from '../../errors/index.js';
 
 const defaultWorkerPath = fileURLToPath(new URL('./job-worker.js', import.meta.url));
 const TERMINAL_STATUSES = new Set(['completed', 'failed']);
 
+function serviceReason(code) {
+  switch (code) {
+    case ERROR_CODE.UNAUTHENTICATED: return ERROR_REASON.AUTH_INVALID;
+    case ERROR_CODE.PERMISSION_DENIED: return ERROR_REASON.PERMISSION_DENIED;
+    case ERROR_CODE.NOT_FOUND: return ERROR_REASON.TARGET_NOT_FOUND;
+    case ERROR_CODE.ABORTED: return ERROR_REASON.CONFLICT;
+    case ERROR_CODE.RESOURCE_EXHAUSTED: return ERROR_REASON.CAPACITY_EXHAUSTED;
+    case ERROR_CODE.UNAVAILABLE: return ERROR_REASON.TRANSPORT_UNREACHABLE;
+    case ERROR_CODE.DEADLINE_EXCEEDED: return ERROR_REASON.DEADLINE_EXCEEDED;
+    case ERROR_CODE.INVALID_ARGUMENT: return ERROR_REASON.INPUT_INVALID;
+    default: return ERROR_REASON.INTERNAL;
+  }
+}
+
 export function serviceError(status, message, code) {
-  return Object.assign(new Error(message), { status, code });
+  const canonical = code === 'CONFLICT' ? ERROR_CODE.ABORTED : (Object.values(ERROR_CODE).includes(code) ? code : ERROR_CODE.INTERNAL);
+  const envelope = createErrorEnvelope({
+    code: canonical,
+    reason: serviceReason(canonical),
+    message,
+    http_status: status,
+    retryable: [429, 503, 504].includes(Number(status)),
+    source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' },
+    resolution_owner: canonical === ERROR_CODE.UNAVAILABLE ? 'agentsam' : undefined,
+    domain: 'knowledge',
+    stage: 'request',
+  });
+  return new AgentSamError(envelope);
+}
+
+function decodeFailure(row) {
+  if (row?.failure_json) {
+    try { return parseError(row.failure_json); }
+    catch {
+      return createErrorEnvelope({
+        reason: ERROR_REASON.INTERNAL_CONTRACT_VIOLATION,
+        message: 'Stored knowledge failure could not be decoded.',
+        source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' },
+        domain: 'knowledge',
+        stage: 'persistence',
+      });
+    }
+  }
+  if (!row?.error) return null;
+  return createErrorEnvelope({
+    reason: ERROR_REASON.EXECUTION_FAILED,
+    message: row.error,
+    source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'legacy_job_row' },
+    domain: 'knowledge',
+    stage: 'execute',
+  });
 }
 
 function decode(row) {
-  return row && {
+  if (!row) return null;
+  const failure = decodeFailure(row);
+  return {
     id: row.id,
     status: row.status,
     attempts: row.attempts,
     created_at: row.created_at,
     updated_at: row.updated_at,
     result: row.result ? JSON.parse(row.result) : null,
-    error: row.error,
+    failure,
+    error: failure?.message || row.error || null,
   };
 }
 
@@ -100,10 +160,22 @@ export function createKnowledgeJobEngine({
   db.exec(`PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000;
     CREATE TABLE IF NOT EXISTS jobs (id TEXT PRIMARY KEY, idem TEXT UNIQUE, digest TEXT NOT NULL,
       payload TEXT NOT NULL, status TEXT NOT NULL, attempts INTEGER NOT NULL DEFAULT 0,
-      created_at TEXT NOT NULL, updated_at TEXT NOT NULL, result TEXT, error TEXT);
+      created_at TEXT NOT NULL, updated_at TEXT NOT NULL, result TEXT, error TEXT, failure_json TEXT);
     CREATE INDEX IF NOT EXISTS jobs_pending ON jobs(status, created_at);`);
+  const columns = new Set(db.prepare('PRAGMA table_info(jobs)').all().map(row => row.name));
+  if (!columns.has('failure_json')) db.exec('ALTER TABLE jobs ADD COLUMN failure_json TEXT');
   fs.chmodSync(jobsFile, 0o600);
-  db.prepare("UPDATE jobs SET status=CASE WHEN attempts>=3 THEN 'failed' ELSE 'queued' END, error=CASE WHEN attempts>=3 THEN 'Interrupted three times; submit a new job after investigation.' ELSE NULL END WHERE status='running'").run();
+  const interruptedFailure = createErrorEnvelope({
+    reason: ERROR_REASON.EXECUTION_FAILED,
+    message: 'Interrupted three times; submit a new job after investigation.',
+    source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' },
+    domain: 'knowledge',
+    stage: 'recovery',
+  });
+  db.prepare("UPDATE jobs SET status=CASE WHEN attempts>=3 THEN 'failed' ELSE 'queued' END, error=CASE WHEN attempts>=3 THEN ? ELSE NULL END, failure_json=CASE WHEN attempts>=3 THEN ? ELSE NULL END WHERE status='running'").run(
+    interruptedFailure.message,
+    JSON.stringify(interruptedFailure),
+  );
 
   let child = null;
   let closing = false;
@@ -120,11 +192,17 @@ export function createKnowledgeJobEngine({
     }
     if (TERMINAL_STATUSES.has(job.status)) watchers.delete(job.id);
   };
-  const updateStatus = (id, status, { result = null, error = null } = {}) => {
-    db.prepare('UPDATE jobs SET status=?,result=?,error=?,updated_at=? WHERE id=?').run(
+  const updateStatus = (id, status, { result = null, failure = null, error = null } = {}) => {
+    const normalizedFailure = failure
+      ? normalizeError(failure, { source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' }, domain: 'knowledge', stage: 'execute' })
+      : error
+        ? createErrorEnvelope({ reason: ERROR_REASON.EXECUTION_FAILED, message: error, source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' }, domain: 'knowledge', stage: 'execute' })
+        : null;
+    db.prepare('UPDATE jobs SET status=?,result=?,error=?,failure_json=?,updated_at=? WHERE id=?').run(
       status,
       result === null ? null : JSON.stringify(result),
-      error,
+      normalizedFailure?.message || null,
+      normalizedFailure ? JSON.stringify(normalizedFailure) : null,
       new Date().toISOString(),
       id,
     );
@@ -145,15 +223,49 @@ export function createKnowledgeJobEngine({
     child = fork(workerPath, [], { execArgv: [], stdio: ['ignore', 'ignore', 'ignore', 'ipc'], env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } });
     const timer = setTimeout(() => { timedOut = true; child?.kill('SIGKILL'); }, jobTimeoutMs);
     child.once('message', value => { response = value; });
-    child.once('error', () => { response = { ok: false, error: 'Could not start indexing process.' }; });
+    child.once('error', (cause) => {
+      response = {
+        ok: false,
+        failure: createErrorEnvelope({
+          reason: ERROR_REASON.INTERNAL_DEPENDENCY_FAILED,
+          message: 'Could not start indexing process.',
+          source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_worker' },
+          domain: 'knowledge',
+          stage: 'spawn',
+          native: { code: cause?.code || null, exception_type: cause?.name || null, stack: cause?.stack || null },
+        }),
+      };
+    });
     child.once('close', () => {
       clearTimeout(timer);
       child = null;
       if (!closing) {
         const ok = response?.ok && !timedOut;
+        let failure = null;
+        if (!ok) {
+          if (timedOut) {
+            failure = createErrorEnvelope({
+              reason: ERROR_REASON.EXECUTION_TIMEOUT,
+              message: 'Knowledge job exceeded its time limit; narrow the scope and retry.',
+              source: { kind: 'runtime', name: 'agentsam-knowledge-worker' },
+              domain: 'knowledge',
+              stage: 'execute',
+            });
+          } else if (response?.failure) {
+            failure = normalizeError(response.failure, { source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_worker' }, domain: 'knowledge', stage: 'execute' });
+          } else {
+            failure = createErrorEnvelope({
+              reason: ERROR_REASON.EXECUTION_FAILED,
+              message: response?.error || 'Indexing process exited unexpectedly.',
+              source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_worker' },
+              domain: 'knowledge',
+              stage: 'execute',
+            });
+          }
+        }
         updateStatus(row.id, ok ? 'completed' : 'failed', {
           result: ok ? response.result : null,
-          error: ok ? null : timedOut ? 'Job exceeded its time limit; narrow the scope.' : response?.error || 'Indexing process exited unexpectedly.',
+          failure,
         });
       }
       pumping = false;
@@ -162,7 +274,17 @@ export function createKnowledgeJobEngine({
     const payload = JSON.parse(row.payload);
     const registered = registry[payload.request.repository];
     if (!registered || registered.config.repository_id !== payload.config.repository_id || fingerprint(registered.config.scope) !== payload.registered_scope || (!allowEmbeddings && ((payload.request.embed && payload.request.operation !== 'plan') || payload.request.semantic))) {
-      response = { ok: false, error: 'Repository registration changed; resubmit this job.' };
+      response = {
+        ok: false,
+        failure: createErrorEnvelope({
+          reason: ERROR_REASON.REPOSITORY_CHANGED,
+          message: 'Repository registration changed; resubmit this job.',
+          source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'repository_registry' },
+          domain: 'repository',
+          stage: 'execute',
+          resource: { type: 'repository', id: payload.config.repository_id || null },
+        }),
+      };
       child.kill();
       return;
     }

package/src/knowledge/service/job-worker.js

@@ -3,12 +3,27 @@ import { openSqliteStore } from '../stores/sqlite.js';
 import { createGeminiEmbedder } from '../providers/gemini.js';
 import { inventory } from '../source.js';
 import { scopeKey } from '../config.js';
+import {
+  AgentSamError,
+  ERROR_REASON,
+  createErrorEnvelope,
+  normalizeError,
+} from '../../errors/index.js';
 
 // Parsing and vector ranking run in a child process, keeping HTTP acceptance responsive.
 process.once('message', async ({ root, config, filename, request, maxFiles }) => {
   let store;
   try {
-    if (request.operation !== 'search' && inventory(root, config.scope).length > maxFiles) throw new Error(`Scope exceeds ${maxFiles} files; choose a smaller include set.`);
+    if (request.operation !== 'search' && inventory(root, config.scope).length > maxFiles) throw new AgentSamError(createErrorEnvelope({
+      reason: ERROR_REASON.INPUT_OUT_OF_RANGE,
+      message: `Scope exceeds ${maxFiles} files; choose a smaller include set.`,
+      source: { kind: 'user', name: 'knowledge_request' },
+      resolution_owner: 'user',
+      domain: 'knowledge',
+      stage: 'inventory',
+      remediation: { action: 'reduce_scope', message: 'Narrow the repository include scope and retry.' },
+      resource: { type: 'repository', id: config.repository_id || null },
+    }));
     store = await openSqliteStore(filename);
     const embedder = request.operation !== 'plan' && (request.embed || request.semantic) ? createGeminiEmbedder({ apiKey: process.env.GEMINI_API_KEY }) : undefined;
     let result;
@@ -18,7 +33,15 @@ process.once('message', async ({ root, config, filename, request, maxFiles }) =>
       const generation = request.generation_id ? await store.getGeneration(scopeKey(config), request.generation_id) : await store.active(scopeKey(config));
       const under = (file, selection) => selection === '.' || file === selection || file.startsWith(selection + '/');
       if (generation?.files.some(file => !config.scope.include.some(p => under(file.path, p)) || config.scope.exclude.some(p => under(file.path, p)))) {
-        throw new Error('Generation exceeds the requested scope; select a matching scope or reindex.');
+        throw new AgentSamError(createErrorEnvelope({
+          reason: ERROR_REASON.PRECONDITION_FAILED,
+          message: 'Generation exceeds the requested scope; select a matching scope or reindex.',
+          source: { kind: 'user', name: 'knowledge_request' },
+          domain: 'knowledge',
+          stage: 'search',
+          remediation: { action: 'change_configuration', message: 'Select a matching indexed scope or reindex the requested scope.' },
+          resource: { type: 'repository', id: config.repository_id || null },
+        }));
       }
       result = await retrieve({ store, config, text: request.query, semantic: request.semantic, embedder,
         topK: request.top_k, tokenBudget: request.token_budget, generationId: request.generation_id });
@@ -27,8 +50,14 @@ process.once('message', async ({ root, config, filename, request, maxFiles }) =>
     process.send({ ok: true, result }, () => process.exit(0));
   } catch (error) {
     await store?.close();
-    // Provider error strings may include sensitive request details. Never persist them.
-    const message = request.embed || request.semantic ? 'Embedding job failed; check provider configuration, budgets, and availability.' : String(error.message).slice(0, 500);
-    process.send({ ok: false, error: message }, () => process.exit(1));
+    const failure = normalizeError(error, {
+      source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_worker' },
+      domain: 'knowledge',
+      stage: request.embed || request.semantic ? 'embedding' : request.operation || 'execute',
+      message: request.embed || request.semantic
+        ? 'Embedding job failed; inspect the canonical failure for provider/configuration details.'
+        : undefined,
+    });
+    process.send({ ok: false, failure }, () => process.exit(1));
   }
 });

package/src/knowledge/service/server.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createBearerTokenVerifier } from './auth.js';
 import { createKnowledgeJobEngine, serviceError } from './job-engine.js';
+import { normalizeError, toHttpError } from '../../errors/index.js';
 
 async function readBody(req) {
   const chunks = [];
@@ -44,7 +45,15 @@ export async function startKnowledgeHttpServer({ engine, token, verifyToken, por
       const { job, created } = engine.submitJob(await readBody(req), { idempotencyKey: req.headers['idempotency-key'] });
       return send(created ? 202 : 200, job);
     } catch (error) {
-      if (!res.writableEnded) send(error.status || 500, { error: error.status ? error.message : 'Service request failed.' });
+      if (!res.writableEnded) {
+        const envelope = normalizeError(error, {
+          source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'http_server' },
+          domain: 'knowledge',
+          stage: 'request',
+        });
+        const httpError = toHttpError(envelope);
+        send(httpError.status, httpError.body);
+      }
     }
   });
   server.requestTimeout = 15000;

package/src/knowledge/store-discovery.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_PATH, readConfig, validateConfig, defaultConfig } from './config.js';
+import { findCliProjectRoot } from '../lib/cli-preferences.js';
+import { runtimeDatabasePath } from '../local/runtime-store.js';
+import { getRepositoryId, portableRepositoryIdFromGit, tryReadProjectConfig } from '../lib/project-config.js';
+
+// Configuration evidence only. No connection probes, credential reads, or schema writes.
+export async function discoverProjectStores(cwd, env = process.env) {
+  const root = findCliProjectRoot(cwd);
+  const config = fs.existsSync(path.join(root, CONFIG_PATH)) ? readConfig(root) : null;
+  const candidates = [
+    { id: 'runtime:sqlite', driver: 'sqlite', role: 'runtime', path: runtimeDatabasePath(root), selected: true },
+    { id: 'knowledge:sqlite', driver: 'sqlite', role: 'knowledge', path: path.join(root, '.agentsam/knowledge/index.sqlite'), selected: !config || config.storage.driver === 'sqlite', selectable: true },
+  ];
+  const envNames = new Set(['AGENTSAM_DATABASE_URL', 'DATABASE_URL', 'POSTGRES_URL', config?.storage?.connection_env].filter(Boolean));
+  for (const name of envNames) {
+    if (!Object.hasOwn(env, name) && name !== config?.storage?.connection_env) continue;
+    candidates.push({ id: `knowledge:postgres:${name}`, driver: 'postgres', role: 'knowledge', connection_env: name, configured: Boolean(env[name]), selected: config?.storage?.driver === 'postgres' && config.storage.connection_env === name, selectable: true });
+  }
+  const warnings = [];
+  let visited = 0;
+  const skip = new Set(['node_modules', '.git', '.agentsam', '.output', 'dist', 'build', 'vendor', '.wrangler']);
+  const configs = [];
+  function scan(dir, depth) {
+    if (depth > 5 || visited >= 4000) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (++visited >= 4000) break;
+      if (entry.isSymbolicLink() || skip.has(entry.name)) continue;
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory()) scan(file, depth + 1);
+      else if (['wrangler.json', 'wrangler.jsonc'].includes(entry.name)) configs.push(file);
+      else if (entry.name === 'wrangler.toml') warnings.push(`${path.relative(root, file)}: TOML discovery is not implemented; inspect this configuration explicitly.`);
+    }
+  }
+  scan(root, 0);
+  if (visited >= 4000) warnings.push('Discovery reached its 4000-entry bound; inspect additional config paths explicitly.');
+  if (configs.length) {
+    const { parseConfigFileTextToJson } = await import('typescript');
+    for (const file of configs) {
+      const source = path.relative(root, file);
+      if (fs.statSync(file).size > 1024 * 1024) { warnings.push(`${source}: configuration too large`); continue; }
+      const parsed = parseConfigFileTextToJson(file, fs.readFileSync(file, 'utf8'));
+      if (parsed.error) { warnings.push(`${source}: invalid JSONC`); continue; }
+      const add = (cfg, environment = null) => {
+        for (const [key, driver, label] of [['d1_databases', 'd1', 'database_name'], ['hyperdrive', 'postgres-hyperdrive', 'id'], ['r2_buckets', 'r2', 'bucket_name']]) {
+          for (const binding of Array.isArray(cfg?.[key]) ? cfg[key] : []) {
+            candidates.push({ id: `${source}:${environment || 'default'}:${binding.binding}`, driver, role: 'application', binding: binding.binding, name: binding[label], source, environment, selectable: false, status: 'declared; connectivity not verified' });
+          }
+        }
+      };
+      add(parsed.config);
+      for (const [environment, cfg] of Object.entries(parsed.config?.env || {})) add(cfg, environment);
+    }
+  }
+  return { root, candidates, warnings, knowledge_config: CONFIG_PATH };
+}
+
+export function selectKnowledgeStore(cwd, driver, connectionEnv) {
+  const root = findCliProjectRoot(cwd);
+  if (!['sqlite', 'postgres'].includes(driver)) throw new Error('knowledge_store_adapter_unavailable: choose sqlite or postgres; D1 application bindings retain their existing authority');
+  const filename = path.join(root, CONFIG_PATH);
+  let config;
+  if (fs.existsSync(filename)) config = readConfig(root);
+  else {
+    const repositoryId = getRepositoryId(tryReadProjectConfig(root)) || portableRepositoryIdFromGit(root);
+    if (!repositoryId) throw new Error('repository_identity_required: run agentsam init . --yes first');
+    config = defaultConfig({ repositoryId });
+  }
+  config.storage = driver === 'sqlite' ? { driver } : { driver, connection_env: connectionEnv || 'AGENTSAM_DATABASE_URL' };
+  config = validateConfig(config);
+  fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  const temp = `${filename}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(temp, filename);
+  return { storage: config.storage, config: CONFIG_PATH, next: driver === 'sqlite' ? 'agentsam index run' : 'agentsam index setup-store', note: 'Selection saved. Existing data remains in its original store; no migration or connection probe ran.' };
+}

package/src/lib/account-session.js

@@ -147,8 +147,14 @@ export function resolveBrowserSessionCredential(options = {}) {
  */
 export function resolveAccountAuth(options = {}) {
   const apiKey = resolveAccountApiKey(options);
-  if (apiKey.value || apiKey.error) return apiKey;
-  return resolveBrowserSessionCredential(options);
+  if (apiKey.value) return apiKey;
+  if (clean(options.explicit) && apiKey.error) return apiKey;
+  const browser = resolveBrowserSessionCredential(options);
+  if (browser.value) {
+    return apiKey.error ? { ...browser, fallback_error: apiKey.error } : browser;
+  }
+  if (browser.error) return browser;
+  return apiKey.error ? apiKey : browser;
 }
 
 export function describeAccountSession(options = {}) {

package/src/lib/agent-instructions.js

@@ -6,6 +6,9 @@ import { findProjectRules } from './project-rules.js';
 export const AGENT_RUNTIME_FILENAME = 'AGENTSAM.md';
 export const AGENT_INSTRUCTION_PRECEDENCE = Object.freeze(['AGENTSAM.md', '.agentsamrules']);
 
+/** Provider/editor adapters that must redirect to AGENTSAM.md — never compiled as policy. */
+export const AGENT_INSTRUCTION_COMPAT_SHIMS = Object.freeze(['AGENTS.md', 'CLAUDE.md']);
+
 function sha256(value) {
   return `sha256:${createHash('sha256').update(value).digest('hex')}`;
 }

package/src/lib/auth.js

@@ -137,12 +137,15 @@ export async function refreshAccountSession(options = {}) {
  */
 export async function resolveAccountAuthority(options = {}) {
   const apiKey = resolveAccountApiKey(options);
-  if (apiKey.value || apiKey.error) return apiKey;
+  if (apiKey.value) return apiKey;
+  if (clean(options.explicit) && apiKey.error) return apiKey;
 
   let session = readAccountSession(options);
-  if (!session?.access_token) return { value: '', source: null, kind: null, session: null };
+  if (!session?.access_token) {
+    return apiKey.error ? apiKey : { value: '', source: null, kind: null, session: null };
+  }
 
-  if (isBrowserSessionExpired(session, options)) {
+  if (options.forceRefresh === true || isBrowserSessionExpired(session, options)) {
     if (!session.refresh_token) {
       return {
         value: '',
@@ -171,6 +174,7 @@ export async function resolveAccountAuthority(options = {}) {
     source: 'agentsam_browser_oauth',
     kind: 'browser_oauth',
     session,
+    fallback_error: apiKey.error || null,
   };
 }
 

package/src/lib/cad/blender.js

@@ -4,9 +4,11 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { runProcess } from '../../security/process.js';
+import { probeDockerServiceHealth, executeBlenderDocker } from './docker-executor.js';
 
 const sdkRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
-export const BLENDER_ADAPTER_PATH = path.join(sdkRoot, 'services/cad/blender/adapter.py');
+const packagedAdapter = path.join(path.dirname(fileURLToPath(import.meta.url)), 'cad/blender/adapter.py');
+export const BLENDER_ADAPTER_PATH = fs.existsSync(packagedAdapter) ? packagedAdapter : 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([
@@ -172,9 +174,46 @@ async function invokeBlender({
   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');
+
+  if (!binary || !fs.existsSync(BLENDER_ADAPTER_PATH)) {
+    try {
+      const dockerHealth = await probeDockerServiceHealth();
+      if (dockerHealth.available && dockerHealth.tools?.blender?.installed) {
+        // Forward the full operation request (recipe/scene/camera/width/height/
+        // format/objects/collection/apply_modifiers as applicable) — the
+        // docker service has no access to `request.output`'s local path, so
+        // strip it and let the container pick its own temp output path.
+        const { output: _localOutput, ...requestRest } = request || {};
+        const inputBase64 = input && fs.existsSync(input) ? fs.readFileSync(input).toString('base64') : null;
+
+        const dockerRes = await executeBlenderDocker({
+          operation,
+          request: requestRest,
+          inputBase64,
+          format: requestRest.format
+            || (operation === 'build' ? 'blend' : operation === 'render_preview' ? 'png' : 'glb'),
+          filename: request.output ? path.basename(request.output) : undefined,
+          timeoutMs: timeout * 1000,
+        });
+
+        if (request.output && dockerRes.artifactBase64) {
+          const outputPath = path.resolve(cwd, request.output);
+          fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+          fs.writeFileSync(outputPath, Buffer.from(dockerRes.artifactBase64, 'base64'));
+        }
+
+        return {
+          result: dockerRes.result || { ok: true, blender_version: dockerHealth.tools.blender.version },
+          binary: `docker://${dockerHealth.service || 'agentsam-cad'}/blender`,
+          duration_ms: dockerRes.durationMs,
+          execution_lane: 'docker_service',
+        };
+      }
+    } catch {}
+
+    throw new Error('Blender is not installed or could not be discovered; use --blender-bin, AGENTSAM_BLENDER_BIN, or launch AgentSam CAD Docker service');
+  }
   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 });

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

@@ -0,0 +1,43 @@
+import {randomUUID} from 'node:crypto';
+import {requireValidProject} from './project-contract.js';
+import {projectHash} from './project-store.js';
+// Reuses blueprint documents + immutable R2 scene snapshots. No new tables.
+// scope is supplied by the authenticated host, never by tool arguments.
+export class D1ProjectStore {
+ constructor({db,objects,bucket,scope}) {
+  if(!scope?.account_id||!scope?.workspace_id||!scope?.tenant_id||!bucket)throw new Error('authenticated_design_scope_required');
+  this.db=db;this.objects=objects;this.bucket=bucket;this.scope=scope;
+ }
+ async read(id,revision){
+  const s=this.scope;
+  const row=await this.db.prepare("SELECT * FROM designstudio_design_blueprints WHERE id=? AND tenant_id=? AND workspace_id=? AND json_extract(intent_json,'$.account_id')=?").bind(id,s.tenant_id,s.workspace_id,s.account_id).first();
+  if(!row)throw new Error('project_not_found');
+  const current=JSON.parse(row.generation_config_json||'{}').project_revision;
+  if(revision==null||revision===current){const p=JSON.parse(row.sketch_json);return {project:p,revision:current,content_hash:projectHash(p)};}
+  const snapshot=await this.db.prepare("SELECT r2_key FROM scene_snapshots WHERE project_id=? AND user_id=? AND workspace_id=? AND tenant_id=? AND version=? AND project_type='CAD_PROJECT'").bind(id,s.account_id,s.workspace_id,s.tenant_id,revision).first();
+  if(!snapshot)throw new Error('revision_not_found');
+  const object=await this.objects.get(snapshot.r2_key);if(!object)throw new Error('revision_object_missing');
+  const saved=JSON.parse(await object.text());requireValidProject(saved.project);if(saved.content_hash!==projectHash(saved.project))throw new Error('revision_digest_mismatch');return saved;
+ }
+ async save(project,expectedRevision,message='Saved project'){
+  requireValidProject(project);
+  if(!Number.isSafeInteger(expectedRevision)||expectedRevision<0)throw new Error('expected_revision_required');
+  const s=this.scope,revision=expectedRevision+1,now=Math.floor(Date.now()/1000),id='scene_'+randomUUID().replaceAll('-','');
+  const p={...structuredClone(project),version:revision,updatedAt:Date.now()};
+  const saved={project:p,revision,content_hash:projectHash(p),message,created_at:now};
+  const key='design-projects/'+encodeURIComponent(s.account_id)+'/'+encodeURIComponent(p.id)+'/'+revision+'/'+saved.content_hash+'.json';
+  await this.objects.put(key,JSON.stringify(saved),{httpMetadata:{contentType:'application/json'}});
+  const statements=[];
+  if(expectedRevision===0){
+   statements.push(this.db.prepare("INSERT INTO designstudio_design_blueprints (id,tenant_id,workspace_id,title,intent_json,sketch_json,generation_config_json,status) VALUES (?,?,?,?,?,?,?,'structured')").bind(p.id,s.tenant_id,s.workspace_id,p.name,JSON.stringify({account_id:s.account_id,contract:'cad.project.v1'}),JSON.stringify(p),JSON.stringify({project_revision:revision,content_hash:saved.content_hash})));
+  }else{
+   statements.push(this.db.prepare("UPDATE designstudio_design_blueprints SET title=?,sketch_json=?,generation_config_json=json_set(generation_config_json,'$.project_revision',?,'$.content_hash',?),updated_at=datetime('now') WHERE id=? AND tenant_id=? AND workspace_id=? AND json_extract(intent_json,'$.account_id')=? AND json_extract(generation_config_json,'$.project_revision')=?").bind(p.name,JSON.stringify(p),revision,saved.content_hash,p.id,s.tenant_id,s.workspace_id,s.account_id,expectedRevision));
+  }
+  // D1 batch is transactional; changes() guards the snapshot against a failed CAS.
+  statements.push(this.db.prepare("INSERT INTO scene_snapshots (id,workspace_id,user_id,tenant_id,name,project_type,entity_count,r2_key,r2_bucket,project_id,version,description,created_at,updated_at) SELECT ?,?,?,?,?,'CAD_PROJECT',?,?,?,?,?,?,?,? WHERE changes()=1").bind(id,s.workspace_id,s.account_id,s.tenant_id,p.name,p.walls.length+p.rooms.length+p.doors.length+p.windows.length,key,this.bucket,p.id,revision,message,now,now));
+  let results;try{results=await this.db.batch(statements);}catch(e){throw new Error('project_save_failed:'+e.message);}
+  if(results[0]?.meta?.changes!==1)throw new Error('revision_conflict');
+  return saved;
+ }
+ async restore(id,revision,expectedRevision){const row=await this.read(id,revision);return this.save(row.project,expectedRevision,'Restored revision '+revision);}
+}