@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.9

package/src/local/sqlite.js

@@ -90,6 +90,23 @@ export async function createLocalSqliteDatabase(filePath = '.agentsam/data/agent
         },
       };
     },
+    async batch(statements = []) {
+      database.exec('BEGIN IMMEDIATE');
+      try {
+        const results = [];
+        for (const statement of statements) {
+          if (!statement || typeof statement.run !== 'function') {
+            throw new TypeError('Local SQLite batch entries must expose run()');
+          }
+          results.push(await statement.run());
+        }
+        database.exec('COMMIT');
+        return results;
+      } catch (error) {
+        try { database.exec('ROLLBACK'); } catch {}
+        throw error;
+      }
+    },
     exec(sql) {
       database.exec(sql);
     },

package/src/local-engine/assets.js

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const ASSET_MANIFEST_SCHEMA = 'agentsam.local-model-assets.v1';
+export function agentsamHome(env = process.env) {
+  const configured = String(env.AGENTSAM_HOME || '').trim();
+  return configured ? path.resolve(configured.replace(/^~(?=\/|$)/, os.homedir())) : path.join(os.homedir(), '.agentsam');
+}
+export function assetManifestPath(env = process.env) { return path.join(agentsamHome(env), 'models', 'manifest.v1.json'); }
+function safeStat(file) { try { return fs.statSync(file); } catch { return null; } }
+function fileId(stat) { return stat ? `${stat.dev}:${stat.ino}` : null; }
+export function readAssetManifest(env = process.env) {
+  const file = assetManifestPath(env);
+  if (!fs.existsSync(file)) return { schema_version: ASSET_MANIFEST_SCHEMA, generated_at: null, assets: [] };
+  try { const parsed = JSON.parse(fs.readFileSync(file, 'utf8')); return parsed?.schema_version === ASSET_MANIFEST_SCHEMA ? parsed : { schema_version: ASSET_MANIFEST_SCHEMA, generated_at: null, assets: [] }; } catch { return { schema_version: ASSET_MANIFEST_SCHEMA, generated_at: null, assets: [] }; }
+}
+function writeManifest(manifest, env = process.env) {
+  const file = assetManifestPath(env); fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`; fs.writeFileSync(temp, JSON.stringify(manifest, null, 2) + '\n', { mode: 0o600 }); fs.renameSync(temp, file); return file;
+}
+export function adoptAsset(file, metadata = {}, options = {}) {
+  const absolute = path.resolve(file); const stat = safeStat(absolute);
+  if (!stat || !stat.isFile()) throw new Error(`model asset is not a regular file: ${absolute}`);
+  const env = options.env || process.env; const manifest = readAssetManifest(env);
+  const asset = { id: metadata.id || crypto.createHash('sha256').update(`${absolute}:${stat.size}:${stat.mtimeMs}`).digest('hex').slice(0, 16), engine_id: metadata.engine_id || null, model: metadata.model || path.basename(absolute), format: metadata.format || path.extname(absolute).slice(1) || 'unknown', canonical_path: absolute, reference: 'external', size_bytes: stat.size, file_id: fileId(stat), digest: metadata.digest || null, seen_at: new Date().toISOString() };
+  const assets = manifest.assets.filter((row) => row.canonical_path !== absolute); assets.push(asset);
+  const next = { ...manifest, schema_version: ASSET_MANIFEST_SCHEMA, generated_at: new Date().toISOString(), assets }; const manifestPath = writeManifest(next, env);
+  return { asset, manifest_path: manifestPath, copied: false };
+}
+export function auditAssets(options = {}) {
+  const env = options.env || process.env; const manifest = readAssetManifest(env);
+  const assets = manifest.assets.map((asset) => { const stat = safeStat(asset.canonical_path); return { ...asset, exists: Boolean(stat), current_size_bytes: stat?.size || null, current_file_id: fileId(stat), stale: !stat || stat.size !== asset.size_bytes }; });
+  const byFile = new Map(); for (const asset of assets) if (asset.file_id) byFile.set(asset.file_id, [...(byFile.get(asset.file_id) || []), asset.id]);
+  return { schema_version: ASSET_MANIFEST_SCHEMA, generated_at: new Date().toISOString(), root: path.join(agentsamHome(env), 'models'), assets, duplicates: [...byFile.entries()].filter(([, ids]) => ids.length > 1).map(([file_id, ids]) => ({ file_id, asset_ids: ids })) };
+}

package/src/local-engine/audit.js

@@ -0,0 +1,133 @@
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { executable, runCommand } from './runtime.js';
+
+export const COMPUTE_AUDIT_SCHEMA = 'agentsam.compute.audit.v1';
+
+function command(command, args = [], runner = spawnSync) {
+  const result = runner(command, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 });
+  return { ok: result.status === 0, stdout: String(result.stdout || '').trim(), stderr: String(result.stderr || '').trim(), status: result.status };
+}
+
+function value(text, key) {
+  const match = String(text || '').match(new RegExp(`^${key}:\\s*(.+)$`, 'mi'));
+  return match?.[1]?.trim() || null;
+}
+
+function bytes(valueText) {
+  const n = Number(valueText);
+  if (Number.isFinite(n) && n > 0) return Math.floor(n);
+  const match = String(valueText || '').match(/([\d.]+)\s*(GB|TB|MB)/i);
+  if (!match) return null;
+  const factor = { mb: 1024 ** 2, gb: 1024 ** 3, tb: 1024 ** 4 }[match[2].toLowerCase()];
+  return Math.floor(Number(match[1]) * factor);
+}
+
+export function parseSystemProfilerHardware(text) {
+  const chip = text.match(/Chip:\s*(.+)/i)?.[1]?.trim() || text.match(/Processor Name:\s*(.+)/i)?.[1]?.trim() || null;
+  const memory = text.match(/Memory:\s*(.+)/i)?.[1]?.trim() || null;
+  const cores = text.match(/Total Number of Cores:\s*(.+)/i)?.[1]?.trim() || null;
+  return { chip, unified_memory_bytes: bytes(memory), core_summary: cores };
+}
+
+export function parseAppleAudit({ sysctlText = '', profilerText = '', platform = process.platform, arch = process.arch } = {}) {
+  const hardware = parseSystemProfilerHardware(profilerText);
+  const chip = hardware.chip || value(sysctlText, 'machdep.cpu.brand_string') || value(sysctlText, 'hw.model');
+  const memory = hardware.unified_memory_bytes || bytes(value(sysctlText, 'hw.memsize'));
+  const appleSilicon = platform === 'darwin' && (arch === 'arm64' || /apple\s*m[1-9]/i.test(chip || ''));
+  return {
+    schema_version: COMPUTE_AUDIT_SCHEMA,
+    generated_at: new Date().toISOString(),
+    host: { platform, arch, hostname: os.hostname() },
+    apple_silicon: appleSilicon,
+    chip: { name: chip, family: chip?.match(/Apple\s+(M\d[^ ]*)/i)?.[1] || null, cores: hardware.core_summary },
+    memory: { unified_memory_bytes: memory, vram_bytes: null, model: appleSilicon ? 'unified' : 'unknown' },
+    metal: { available: appleSilicon ? null : false, features: [], evidence: appleSilicon ? 'not_probed' : 'non_apple_host' },
+    evidence: [],
+    warnings: appleSilicon ? ['Metal feature probing requires the macOS native helper and is not inferred from chip identity.'] : ['Apple Silicon audit is unavailable on this host.'],
+  };
+}
+
+export function auditAppleHost(options = {}) {
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  if (platform !== 'darwin') return parseAppleAudit({ platform, arch });
+  const sysctl = command('sysctl', ['-n', 'hw.model', 'hw.memsize'], options.runner || spawnSync);
+  const profiler = command('system_profiler', ['SPHardwareDataType', 'SPDisplaysDataType'], options.runner || spawnSync);
+  const audit = parseAppleAudit({ sysctlText: sysctl.stdout, profilerText: profiler.stdout, platform, arch });
+  audit.evidence.push({ source: 'sysctl', ok: sysctl.ok });
+  audit.evidence.push({ source: 'system_profiler', ok: profiler.ok });
+  audit.host.env_override = Boolean(env.AGENTSAM_HOME);
+  return audit;
+}
+
+export function auditTools(options = {}) {
+  const engines = [
+    { id: 'ollama', commands: ['ollama'] },
+    { id: 'llama.cpp', commands: ['llama-server', 'llama-cli'] },
+    { id: 'mlx-lm', commands: ['mlx_lm.server', 'mlx_lm'] },
+  ];
+  return engines.map((engine) => {
+    const hits = engine.commands.map((name) => ({ name, path: executable(name, options.env || process.env) })).filter((row) => row.path);
+    const version = hits[0] ? runCommand(hits[0].name, ['--version'], options).stdout.trim() : null;
+    return { engine_id: engine.id, installed: hits.length > 0, commands: hits, version: version || null };
+  });
+}
+
+function auditLinuxHost(options = {}) {
+  const env = options.env || process.env;
+  const memory = command('free', ['-b'], options.runner || spawnSync);
+  const cpu = command('lscpu', [], options.runner || spawnSync);
+  const osRelease = command('uname', ['-a'], options.runner || spawnSync);
+  const memoryLine = memory.stdout.split(/\n/).find((line) => /^Mem:/i.test(line));
+  const memoryBytes = memoryLine ? Number(memoryLine.trim().split(/\s+/)[1]) || null : null;
+  return {
+    schema_version: COMPUTE_AUDIT_SCHEMA,
+    generated_at: new Date().toISOString(),
+    host: { platform: 'linux', arch: options.arch || process.arch, hostname: os.hostname() },
+    apple_silicon: false,
+    chip: { name: value(cpu.stdout, 'Model name') || value(cpu.stdout, 'Architecture'), family: null, cores: value(cpu.stdout, 'CPU\\(s\\)') },
+    memory: { unified_memory_bytes: null, system_memory_bytes: memoryBytes, vram_bytes: null, model: 'system' },
+    accelerators: [{ id: 'nvidia-smi', available: Boolean(executable('nvidia-smi', env)), evidence: 'optional' }],
+    shells: auditShells(options),
+    evidence: [{ source: 'uname', ok: osRelease.ok }, { source: 'lscpu', ok: cpu.ok }, { source: 'free', ok: memory.ok }],
+    warnings: ['Linux accelerator memory is engine/vendor-specific and is not inferred as system VRAM.'],
+  };
+}
+
+function auditWindowsHost(options = {}) {
+  const env = options.env || process.env;
+  const powershell = executable('pwsh', env) || executable('powershell.exe', env);
+  const result = powershell ? command(powershell, ['-NoProfile', '-NonInteractive', '-Command', '$c=Get-CimInstance Win32_ComputerSystem; $g=Get-CimInstance Win32_VideoController; [pscustomobject]@{model=$c.Model;memory=$c.TotalPhysicalMemory;gpu=($g.Name -join ";")}|ConvertTo-Json -Compress'], options.runner || spawnSync) : { ok: false, stdout: '' };
+  let facts = {}; try { facts = JSON.parse(result.stdout || '{}'); } catch {}
+  return {
+    schema_version: COMPUTE_AUDIT_SCHEMA,
+    generated_at: new Date().toISOString(),
+    host: { platform: 'windows', arch: options.arch || process.arch, hostname: os.hostname() },
+    apple_silicon: false,
+    chip: { name: facts.model || null, family: null, cores: null },
+    memory: { unified_memory_bytes: null, system_memory_bytes: Number(facts.memory) || null, vram_bytes: null, model: 'system' },
+    accelerators: [{ id: 'video-controller', available: Boolean(facts.gpu), name: facts.gpu || null }],
+    shells: auditShells(options),
+    evidence: [{ source: powershell || 'powershell', ok: result.ok }],
+    warnings: ['Windows GPU memory is reported only when the vendor API exposes it; no VRAM estimate is made.'],
+  };
+}
+
+function auditShells(options = {}) {
+  const env = options.env || process.env;
+  return ['pwsh', 'powershell.exe', 'bash', 'zsh', 'sh'].map((name) => ({ id: name, path: executable(name, env), available: Boolean(executable(name, env)) }));
+}
+
+export function auditHost(options = {}) {
+  const platform = options.platform || process.platform;
+  if (platform === 'darwin') return { ...auditAppleHost(options), shells: auditShells(options) };
+  if (platform === 'win32') return auditWindowsHost(options);
+  if (platform === 'linux') return auditLinuxHost(options);
+  return { ...parseAppleAudit({ platform, arch: options.arch || process.arch }), shells: auditShells(options) };
+}
+
+export function auditLocalCompute(options = {}) {
+  return { schema_version: COMPUTE_AUDIT_SCHEMA, generated_at: new Date().toISOString(), hardware: auditHost(options), engines: auditTools(options) };
+}

package/src/local-engine/benchmark.js

@@ -0,0 +1,26 @@
+import { LOCAL_ENGINE_BENCHMARK_SCHEMA } from './contracts.js';
+
+function tokenCount(result) { return Number(result?.usage?.output_tokens || result?.usage?.completion_tokens || String(result?.output_text || '').trim().split(/\s+/).filter(Boolean).length); }
+function validateShape(value, schema) {
+  if (!schema || typeof schema !== 'object') return { valid: true, error: null };
+  if (schema.type === 'object' && (value === null || typeof value !== 'object' || Array.isArray(value))) return { valid: false, error: 'expected_object' };
+  if (schema.type === 'array' && !Array.isArray(value)) return { valid: false, error: 'expected_array' };
+  if (schema.required) for (const key of schema.required) if (!(key in value)) return { valid: false, error: `missing_required:${key}` };
+  if (schema.properties && value && typeof value === 'object') for (const [key, child] of Object.entries(schema.properties)) if (key in value) { const result = validateShape(value[key], child); if (!result.valid) return { valid: false, error: `${key}.${result.error}` }; }
+  return { valid: true, error: null };
+}
+export function validateStructuredOutput(text, schema = null) {
+  try { const value = JSON.parse(String(text || '')); const shape = validateShape(value, schema); return { valid: shape.valid, parse_error: null, schema_error: shape.valid ? null : shape.error, value: shape.valid ? value : null, grammar_enforced: false, tool_arguments_valid: shape.valid }; } catch (error) { return { valid: false, parse_error: error.message, schema_error: null, value: null, grammar_enforced: false, tool_arguments_valid: false }; }
+}
+export async function benchmarkEngine(engine, options = {}) {
+  const runs = Math.max(1, Number(options.runs) || 1); const prompt = options.prompt || 'Reply with a short JSON object containing an answer field.'; const results = [];
+  for (let i = 0; i < runs; i += 1) {
+    const started = performance.now();
+    const result = await engine.chat({ model: options.model, messages: [{ role: 'user', content: prompt }], responseFormat: options.schema ? { type: 'json_object' } : null });
+    const ended = performance.now(); const outputTokens = tokenCount(result); const ttft = Number.isFinite(result?.timing?.ttft_ms) ? result.timing.ttft_ms : null; const elapsed = ended - started;
+    results.push({ run: i + 1, ttft_ms: ttft, elapsed_ms: elapsed, output_tokens: outputTokens, tokens_per_second: elapsed > 0 ? outputTokens / (elapsed / 1000) : null, structured_output: options.schema ? validateStructuredOutput(result.output_text, options.schema) : null });
+  }
+  return { schema_version: LOCAL_ENGINE_BENCHMARK_SCHEMA, engine_id: engine.id, model: options.model || null, generated_at: new Date().toISOString(), fixture: { id: options.fixtureId || 'default-json', prompt_hash: cryptoHash(prompt) }, runs: results, summary: summarize(results), resource: { memory: null, source: 'not_available' }, warnings: ['Memory utilization requires an engine/platform sampler.', 'TTFT is null unless the engine adapter reports a measured first-token time.'] };
+}
+function cryptoHash(value) { let h = 2166136261; for (const char of String(value)) h = Math.imul(h ^ char.charCodeAt(0), 16777619); return (h >>> 0).toString(16); }
+function summarize(rows) { const average = (key) => { const values = rows.map((row) => row[key]).filter((x) => Number.isFinite(x)); return values.length ? values.reduce((a, b) => a + b, 0) / values.length : null; }; return { average_ttft_ms: average('ttft_ms'), average_tokens_per_second: average('tokens_per_second'), valid_structured_outputs: rows.filter((row) => row.structured_output?.valid === true).length, run_count: rows.length }; }

package/src/local-engine/contracts.js

@@ -0,0 +1,101 @@
+import { createToolError, ERROR_CODE, ERROR_REASON } from '@inneranimalmedia/agentsam-errors';
+
+export const LOCAL_ENGINE_SCHEMA = 'agentsam.local-engine.v1';
+export const LOCAL_ENGINE_BENCHMARK_SCHEMA = 'agentsam.engine.benchmark.v1';
+
+export const ENGINE_CAPABILITIES = Object.freeze([
+  'chat', 'chat.streaming', 'chat.tools', 'embed', 'embed.batch',
+  'output.json', 'output.json_schema', 'output.grammar', 'model.load',
+  'model.unload', 'metrics.ttft', 'metrics.tokens_per_second', 'metrics.memory',
+  'runtime.metal', 'runtime.mlx', 'format.gguf', 'format.safetensors',
+]);
+
+export const ENGINE_STATUS = Object.freeze(['installed', 'available', 'unavailable', 'unknown']);
+
+export function clean(value) { return value == null ? '' : String(value).trim(); }
+
+export function normalizeCapability(value) {
+  const id = clean(value).toLowerCase();
+  return ENGINE_CAPABILITIES.includes(id) ? id : null;
+}
+
+export function capabilityCard({ engineId, version = null, model = null, capabilities = {}, evidence = [], status = 'unknown', warnings = [] } = {}) {
+  if (!engineId) throw new TypeError('engineId is required');
+  const normalized = Object.fromEntries(ENGINE_CAPABILITIES.map((id) => [id, capabilities[id] === true]));
+  return Object.freeze({
+    schema_version: LOCAL_ENGINE_SCHEMA,
+    engine_id: clean(engineId),
+    version: version || null,
+    model: model || null,
+    status: ENGINE_STATUS.includes(status) ? status : 'unknown',
+    capabilities: Object.freeze(normalized),
+    evidence: Object.freeze(Array.isArray(evidence) ? evidence.map((row) => ({ ...row })) : []),
+    warnings: Object.freeze(Array.isArray(warnings) ? [...warnings] : []),
+  });
+}
+
+export function engineInventory({ engineId, version = null, installed = false, reachable = false, endpoint = null, models = [], capabilities = {}, evidence = [], warnings = [] } = {}) {
+  return Object.freeze({
+    schema_version: LOCAL_ENGINE_SCHEMA,
+    engine_id: clean(engineId),
+    version: version || null,
+    installed: installed === true,
+    reachable: reachable === true,
+    endpoint: endpoint || null,
+    models: Object.freeze((Array.isArray(models) ? models : []).map((row) => ({ ...row }))),
+    capabilities: Object.freeze({ ...capabilities }),
+    evidence: Object.freeze(Array.isArray(evidence) ? evidence.map((row) => ({ ...row })) : []),
+    warnings: Object.freeze(Array.isArray(warnings) ? [...warnings] : []),
+  });
+}
+
+export function engineError(localCode, message, details = {}) {
+  const unsupported = localCode === 'LOCAL_ENGINE_UNSUPPORTED';
+  const engineId = details.engine_id || details.engineId || 'unknown';
+  return createToolError({
+    tool: `local-engine.${engineId}`,
+    domain: 'runtime',
+    stage: details.operation || 'execute',
+    code: unsupported ? ERROR_CODE.UNIMPLEMENTED : ERROR_CODE.UNAVAILABLE,
+    reason: unsupported ? ERROR_REASON.UNSUPPORTED_OPERATION : ERROR_REASON.PROVIDER_UNAVAILABLE,
+    message: message || localCode,
+    retryable: !unsupported,
+    provider: engineId,
+    native: { code: localCode },
+    details: { ...details, local_code: localCode },
+  });
+}
+
+export function assertEngineContract(engine) {
+  for (const method of ['discover', 'capabilities', 'chat', 'embed', 'unload']) {
+    if (typeof engine?.[method] !== 'function') throw new TypeError(`local engine ${method}() is required`);
+  }
+  return engine;
+}
+
+export function normalizeChatResult(result = {}, engineId = null) {
+  return Object.freeze({
+    schema_version: LOCAL_ENGINE_SCHEMA,
+    engine_id: result.engine_id || engineId,
+    model: result.model || null,
+    status: result.status || 'completed',
+    output_text: String(result.output_text || ''),
+    tool_calls: Object.freeze(Array.isArray(result.tool_calls) ? result.tool_calls.map((row) => ({ ...row })) : []),
+    usage: Object.freeze({ ...(result.usage || {}) }),
+    timing: Object.freeze({ ...(result.timing || {}) }),
+    evidence: Object.freeze(Array.isArray(result.evidence) ? [...result.evidence] : []),
+  });
+}
+
+export function normalizeEmbedResult(result = {}, engineId = null) {
+  return Object.freeze({
+    schema_version: LOCAL_ENGINE_SCHEMA,
+    engine_id: result.engine_id || engineId,
+    model: result.model || null,
+    status: result.status || 'completed',
+    embeddings: Object.freeze(Array.isArray(result.embeddings) ? result.embeddings : []),
+    dimensions: Number(result.dimensions) || 0,
+    usage: Object.freeze({ ...(result.usage || {}) }),
+    evidence: Object.freeze(Array.isArray(result.evidence) ? [...result.evidence] : []),
+  });
+}

package/src/local-engine/engines.js

@@ -0,0 +1,142 @@
+import { resolveOllamaConfig, probeOllama, probeOllamaModel } from '../commands/ollama.js';
+import { createOllamaChatAdapter } from '../providers/ollama-chat.js';
+import { capabilityCard, engineInventory, engineError, normalizeChatResult, normalizeEmbedResult } from './contracts.js';
+import { executable, fetchJson, runCommand, unsupported } from './runtime.js';
+
+function modelNames(body) {
+  return Array.isArray(body?.models) ? body.models.map((row) => ({ name: row.name || row.model || '', size: row.size || null, digest: row.digest || null })).filter((row) => row.name) : [];
+}
+
+export function createOllamaEngine(options = {}) {
+  const env = options.env || process.env;
+  const fetchImpl = options.fetchImpl || fetch;
+  const config = resolveOllamaConfig(options, env);
+  return {
+    id: 'ollama',
+    async discover() {
+      const api = await probeOllama(config, fetchImpl);
+      const binary = runCommand('ollama', ['--version'], { env });
+      return engineInventory({
+        engineId: 'ollama', version: binary.ok ? String(binary.stdout || binary.stderr).trim() : null,
+        installed: binary.installed, reachable: api.online, endpoint: config.baseUrl,
+        models: api.models || [],
+        capabilities: { chat: api.chat_ready, embed: api.embed_ready, 'chat.streaming': false, 'chat.tools': true, 'model.unload': true },
+        evidence: [{ source: 'ollama', endpoint: config.baseUrl, status: api.status }],
+        warnings: api.error ? [api.error] : [],
+      });
+    },
+    async capabilities({ model } = {}) {
+      const probe = await probeOllamaModel(model || config.model, config, fetchImpl);
+      return capabilityCard({ engineId: 'ollama', model: model || config.model, status: probe.ok ? 'available' : 'unavailable', capabilities: {
+        chat: probe.ok, 'chat.streaming': false, 'chat.tools': probe.capabilities?.includes('tools') === true,
+        embed: false, 'output.json': true, 'output.json_schema': false, 'model.unload': true, 'metrics.ttft': true,
+      }, evidence: [{ source: 'ollama/api/show', context_window: probe.context_window, capabilities: probe.capabilities || [] }], warnings: probe.error ? [probe.error] : [] });
+    },
+    async chat(params = {}) {
+      const adapter = createOllamaChatAdapter({ endpoint: config.baseUrl, env, fetchImpl });
+      const result = await adapter.create({ ...params, modelRecord: { provider: 'ollama', provider_model_id: params.model || config.model, context_window: params.context_window || 0 } });
+      return normalizeChatResult({ ...result, timing: result.timing || {} }, 'ollama');
+    },
+    async embed({ model = config.embedModel, inputs = [] } = {}) {
+      const values = Array.isArray(inputs) ? inputs : [inputs];
+      const response = await fetchJson(`${config.baseUrl}/api/embed`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ model, input: values }) }, fetchImpl);
+      if (!response.ok) throw engineError('LOCAL_ENGINE_EMBED_FAILED', response.error || 'Ollama embedding failed', { engine_id: 'ollama' });
+      const embeddings = response.body?.embeddings || (response.body?.embedding ? [response.body.embedding] : []);
+      return normalizeEmbedResult({ model, embeddings, dimensions: embeddings[0]?.length || 0 }, 'ollama');
+    },
+    async unload({ model } = {}) {
+      const response = await fetchJson(`${config.baseUrl}/api/generate`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ model: model || config.model, prompt: '', keep_alive: 0 }) }, fetchImpl);
+      return { schema_version: 'agentsam.local-engine.v1', engine_id: 'ollama', model: model || config.model, unloaded: response.ok, status: response.ok ? 'completed' : 'unavailable', error: response.error || null };
+    },
+  };
+}
+
+function openAiEndpoint(options, defaultUrl) {
+  const env = options.env || process.env;
+  return String(options.endpoint || env[options.envKey || 'AGENTSAM_LOCAL_ENGINE_ENDPOINT'] || defaultUrl).replace(/\/$/, '');
+}
+
+function createOpenAiCompatibleEngine({ id, endpoint, command, versionArgs = ['--version'], env = process.env, capabilities = {}, options = {} }) {
+  const fetchImpl = options.fetchImpl || fetch;
+  return {
+    id,
+    async discover() {
+      const binary = runCommand(command, versionArgs, { env });
+      const health = await fetchJson(`${endpoint}/v1/models`, {}, fetchImpl);
+      return engineInventory({
+        engineId: id,
+        version: binary.ok ? String(binary.stdout || binary.stderr).trim() : null,
+        installed: binary.ok,
+        reachable: health.ok,
+        endpoint,
+        models: modelNames(health.body?.data ? { models: health.body.data.map((row) => ({ name: row.id })) } : health.body),
+        capabilities,
+        evidence: [
+          { source: 'binary-probe', command, binary: binary.binary || null, ok: binary.ok, exit_status: binary.status },
+          { source: 'openai-compatible', endpoint, ok: health.ok, status: health.status },
+        ],
+        warnings: health.error ? [health.error] : [],
+      });
+    },
+    async capabilities({ model = null } = {}) { return capabilityCard({ engineId: id, model, status: 'unknown', capabilities, evidence: [{ source: 'adapter declaration', endpoint }], warnings: ['Model-specific capabilities require a live probe.'] }); },
+    async chat({ model, messages = [], tools = [], responseFormat = null, onEvent, signal } = {}) {
+      const started = performance.now();
+      const response = await fetchJson(`${endpoint}/v1/chat/completions`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ model, messages, tools: tools.length ? tools : undefined, response_format: responseFormat || undefined, stream: false }), signal }, fetchImpl);
+      if (!response.ok) throw engineError('LOCAL_ENGINE_CHAT_FAILED', response.error || `${id} chat failed`, { engine_id: id });
+      const choice = response.body?.choices?.[0] || {};
+      const text = choice.message?.content || '';
+      return normalizeChatResult({ model, output_text: text, tool_calls: choice.message?.tool_calls || [], usage: response.body?.usage || {}, timing: { elapsed_ms: performance.now() - started, ttft_ms: null } }, id);
+    },
+    async embed({ model, inputs = [], signal } = {}) {
+      const response = await fetchJson(`${endpoint}/v1/embeddings`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ model, input: inputs }), signal }, fetchImpl);
+      if (!response.ok) throw engineError('LOCAL_ENGINE_EMBED_FAILED', response.error || `${id} embedding failed`, { engine_id: id });
+      const embeddings = (response.body?.data || []).sort((a, b) => a.index - b.index).map((row) => row.embedding);
+      return normalizeEmbedResult({ model, embeddings, dimensions: embeddings[0]?.length || 0, usage: response.body?.usage || {} }, id);
+    },
+    async unload({ model, signal } = {}) { return { schema_version: 'agentsam.local-engine.v1', engine_id: id, model, unloaded: false, status: 'unsupported', error: unsupported(id, 'unload').message, signal: Boolean(signal) }; },
+  };
+}
+
+export function createMlxLmEngine(options = {}) {
+  const endpoint = openAiEndpoint(options, 'http://127.0.0.1:8080');
+  return createOpenAiCompatibleEngine({
+    id: 'mlx-lm',
+    endpoint,
+    command: options.command || 'python3',
+    versionArgs: options.versionArgs || ['-c', 'import importlib.metadata as m; print(m.version("mlx-lm"))'],
+    env: options.env || process.env,
+    capabilities: {
+      chat: true,
+      'chat.streaming': false,
+      embed: false,
+      'runtime.mlx': process.platform === 'darwin' && process.arch === 'arm64',
+      'runtime.metal': process.platform === 'darwin' && process.arch === 'arm64',
+      'output.json': true,
+    },
+    options,
+  });
+}
+
+export function createLlamaCppEngine(options = {}) {
+  const endpoint = openAiEndpoint(options, 'http://127.0.0.1:8080');
+  return createOpenAiCompatibleEngine({
+    id: 'llama.cpp',
+    endpoint,
+    command: options.command || 'llama-server',
+    env: options.env || process.env,
+    capabilities: {
+      chat: true,
+      'chat.streaming': false,
+      'chat.tools': true,
+      embed: true,
+      'format.gguf': true,
+      'runtime.metal': process.platform === 'darwin',
+      'output.grammar': true,
+      'output.json_schema': true,
+      'model.unload': false,
+    },
+    options,
+  });
+}
+
+export function defaultLocalEngines(options = {}) { return [createOllamaEngine(options), createMlxLmEngine(options.mlx || options), createLlamaCppEngine(options.llamaCpp || options)]; }

package/src/local-engine/index.js

@@ -0,0 +1,18 @@
+import { assertEngineContract } from './contracts.js';
+import { defaultLocalEngines } from './engines.js';
+
+export class LocalEngineRegistry {
+  constructor(engines = defaultLocalEngines()) { this.engines = new Map(engines.map((engine) => [engine.id, assertEngineContract(engine)])); }
+  register(engine) { this.engines.set(engine.id, assertEngineContract(engine)); return this; }
+  get(id) { const engine = this.engines.get(id); if (!engine) throw new Error(`unknown_local_engine:${id}`); return engine; }
+  list() { return [...this.engines.values()].map((engine) => engine.id); }
+  async discover() { return Promise.all([...this.engines.values()].map((engine) => engine.discover())); }
+  async capabilities(request = {}) { return this.get(request.engine_id || request.engineId).capabilities(request); }
+}
+
+export function createLocalEngineRegistry(options = {}) { return new LocalEngineRegistry(options.engines || defaultLocalEngines(options)); }
+export * from './contracts.js';
+export * from './engines.js';
+export * from './audit.js';
+export * from './assets.js';
+export * from './benchmark.js';

package/src/local-engine/runtime.js

@@ -0,0 +1,39 @@
+import { spawnSync } from 'node:child_process';
+import { engineError } from './contracts.js';
+
+export function executable(command, env = process.env) {
+  if (!command) return null;
+  const finder = process.platform === 'win32' ? 'where' : 'which';
+  const result = spawnSync(finder, [command], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env });
+  return result.status === 0 ? String(result.stdout || '').split(/\r?\n/).map((x) => x.trim()).find(Boolean) || null : null;
+}
+
+export function runCommand(command, args = [], options = {}) {
+  const binary = options.binary || executable(command, options.env || process.env);
+  if (!binary) return { ok: false, installed: false, command, args, stdout: '', stderr: '', status: null };
+  const result = spawnSync(binary, args, {
+    encoding: 'utf8',
+    env: options.env || process.env,
+    timeout: options.timeout || 3000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: options.maxBuffer || 4 * 1024 * 1024,
+  });
+  return { ok: result.status === 0, installed: true, command, args, binary, stdout: String(result.stdout || ''), stderr: String(result.stderr || ''), status: result.status, error: result.error || null };
+}
+
+export async function fetchJson(url, init = {}, fetchImpl = fetch) {
+  try {
+    const response = await fetchImpl(url, { ...init, signal: init.signal || AbortSignal.timeout(3000) });
+    const text = await response.text();
+    let body = null;
+    try { body = text ? JSON.parse(text) : null; } catch { body = null; }
+    if (!response.ok) return { ok: false, status: response.status, body, error: `HTTP ${response.status}` };
+    return { ok: true, status: response.status, body };
+  } catch (error) {
+    return { ok: false, status: null, body: null, error: error?.message || String(error) };
+  }
+}
+
+export function unsupported(engineId, operation) {
+  return engineError('LOCAL_ENGINE_UNSUPPORTED', `${engineId} does not support ${operation}`, { engine_id: engineId, operation });
+}

package/src/sam/operations/package-audit.js

@@ -0,0 +1,41 @@
+import { defineSamOperation } from '../define.js';
+import { auditPackages } from '../../commands/package.js';
+
+export const packageAuditOp = defineSamOperation({
+  id: 'package.audit',
+  version: 1,
+  module: 'package',
+  action: 'audit',
+  summary: 'Audit AgentSam package publication intent, registry state, and structural blockers.',
+  purpose:
+    'Establish deterministic package-distribution authority for @inneranimalmedia packages without publishing anything.',
+  outcome:
+    'Return classified package manifests, public-distribution intent, registry state when allowed, and structural blockers.',
+  description:
+    'Discover scoped package manifests, classify public/private intent, optionally query npm registry state, and return a bounded read-only audit.',
+  skill: { id: 'agentsam-progression-guard', help: true },
+  accepts: ['root', 'publicOnly', 'offline'],
+  phases: ['discover_manifests', 'classify_intent', 'resolve_registry_state', 'emit_audit'],
+  execution: {
+    lanes: ['local', 'remote', 'sandbox'],
+    model: 'never',
+    embedding: 'never',
+    network: 'optional',
+    sideEffects: 'none',
+    provider_spend: 'none',
+  },
+  risk: 'read_only',
+  capabilities: ['package.audit'],
+  artifacts: ['package.audit'],
+  cli: { command: [['package', 'audit']] },
+  docs: { section: 'Packages' },
+  status: 'stable',
+  async handler(input = {}, ctx = {}) {
+    const root = input.root || input.cwd || ctx.cwd || process.cwd();
+    return auditPackages({
+      root,
+      publicOnly: input.publicOnly === true || input.public === true,
+      offline: input.offline === true,
+    });
+  },
+});

package/src/sam/seed.js

@@ -8,6 +8,7 @@ import { codebaseindexIngestOp } from './operations/codebaseindex-ingest.js';
 import { planningAstarOp } from './operations/planning-astar.js';
 import { planningGoapOp } from './operations/planning-goap.js';
 import { decisionEvaluateOp } from './operations/decision-evaluate.js';
+import { packageAuditOp } from './operations/package-audit.js';
 
 export const SEED_OPERATIONS = [
   repositoryInspect,
@@ -19,6 +20,7 @@ export const SEED_OPERATIONS = [
   planningAstarOp,
   planningGoapOp,
   decisionEvaluateOp,
+  packageAuditOp,
 ];
 
 let seeded = false;