@inneranimalmedia/agentsam-sdk 2.6.8 → 2.6.9

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/packages/agentsam-nav/dist/Nav.d.ts

@@ -1,43 +0,0 @@
-import { type HTMLAttributes } from 'react';
-import { NavCollapsible, NavCollapsibleContent, NavCollapsibleTrigger } from './NavCollapsible.js';
-import { NavContent } from './NavContent.js';
-import { NavFooter } from './NavFooter.js';
-import { NavGroup, NavGroupLabel } from './NavGroup.js';
-import { NavHeader } from './NavHeader.js';
-import { NavMenu, NavMenuButton, NavMenuChevron, NavMenuItem, NavMenuSub, NavMenuSubButton } from './NavMenu.js';
-import { NavProvider } from './NavProvider.js';
-import { NavTrigger } from './NavTrigger.js';
-import { NavScope, NavSidenav, NavTopbar, NavTopbarLogo, NavTopbarSpacer, NavProjectContext, NavAccountSwitcher, NavFilesResources, NavPinnedSummary, NavConversationActions, NavShareButton, NavOverflowMenu, NavModeSwitcher } from './Surfaces.js';
-declare function NavRoot({ className, children, ...props }: HTMLAttributes<HTMLElement>): import("react").JSX.Element;
-export declare const Nav: typeof NavRoot & {
-    Scope: typeof NavScope;
-    Sidenav: typeof NavSidenav;
-    Topbar: typeof NavTopbar;
-    TopbarLogo: typeof NavTopbarLogo;
-    TopbarSpacer: typeof NavTopbarSpacer;
-    ProjectContext: typeof NavProjectContext;
-    AccountSwitcher: typeof NavAccountSwitcher;
-    FilesResources: typeof NavFilesResources;
-    PinnedSummary: typeof NavPinnedSummary;
-    ConversationActions: typeof NavConversationActions;
-    ShareButton: typeof NavShareButton;
-    OverflowMenu: typeof NavOverflowMenu;
-    ModeSwitcher: typeof NavModeSwitcher;
-    Provider: typeof NavProvider;
-    Header: typeof NavHeader;
-    Content: typeof NavContent;
-    Footer: typeof NavFooter;
-    Group: typeof NavGroup;
-    GroupLabel: typeof NavGroupLabel;
-    Menu: typeof NavMenu;
-    MenuItem: typeof NavMenuItem;
-    MenuButton: typeof NavMenuButton;
-    MenuSub: typeof NavMenuSub;
-    MenuSubButton: typeof NavMenuSubButton;
-    MenuChevron: typeof NavMenuChevron;
-    Collapsible: typeof NavCollapsible;
-    CollapsibleTrigger: typeof NavCollapsibleTrigger;
-    CollapsibleContent: typeof NavCollapsibleContent;
-    Trigger: typeof NavTrigger;
-};
-export {};

package/packages/agentsam-nav/dist/NavCollapsible.d.ts

@@ -1,10 +0,0 @@
-import { type ButtonHTMLAttributes, type HTMLAttributes, type ReactElement, type ReactNode } from 'react';
-export declare function NavCollapsible({ children, defaultOpen }: {
-    children: ReactNode;
-    defaultOpen?: boolean;
-}): import("react").JSX.Element;
-export declare function NavCollapsibleTrigger({ render, children, className, ...props }: ButtonHTMLAttributes<HTMLButtonElement> & {
-    render?: ReactElement;
-    children?: ReactNode;
-}): import("react").JSX.Element;
-export declare function NavCollapsibleContent({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavContent.d.ts

@@ -1,2 +0,0 @@
-import type { HTMLAttributes } from 'react';
-export declare function NavContent({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavFooter.d.ts

@@ -1,2 +0,0 @@
-import type { HTMLAttributes } from 'react';
-export declare function NavFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavGroup.d.ts

@@ -1,3 +0,0 @@
-import type { HTMLAttributes } from 'react';
-export declare function NavGroup({ className, ...props }: HTMLAttributes<HTMLElement>): import("react").JSX.Element;
-export declare function NavGroupLabel({ className, ...props }: HTMLAttributes<HTMLParagraphElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavHeader.d.ts

@@ -1,2 +0,0 @@
-import type { HTMLAttributes } from 'react';
-export declare function NavHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavMenu.d.ts

@@ -1,22 +0,0 @@
-import type { ButtonHTMLAttributes, HTMLAttributes, ReactNode } from 'react';
-export declare function NavMenu({ className, ...props }: HTMLAttributes<HTMLUListElement>): import("react").JSX.Element;
-export declare function NavMenuItem({ className, ...props }: HTMLAttributes<HTMLLIElement>): import("react").JSX.Element;
-export type NavMenuButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
-    icon?: unknown;
-    active?: boolean;
-    itemId?: string;
-    children: ReactNode;
-};
-export declare function NavMenuButton({ icon: Icon, active, itemId, className, children, ...props }: NavMenuButtonProps): import("react").JSX.Element;
-export declare function NavMenuSub({ className, ...props }: HTMLAttributes<HTMLUListElement>): import("react").JSX.Element;
-export type NavMenuSubButtonProps = {
-    href?: string;
-    active?: boolean;
-    className?: string;
-    children?: unknown;
-    onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void;
-};
-export declare function NavMenuSubButton({ active, className, children, ...props }: NavMenuSubButtonProps): import("react").JSX.Element;
-export declare function NavMenuChevron({ className }: {
-    className?: string;
-}): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavProvider.d.ts

@@ -1,35 +0,0 @@
-import { type PropsWithChildren } from 'react';
-import type { NavTheme, NavValue, NavTokens } from './contracts.js';
-export type NavContextValue = {
-    data: NavValue;
-    tokens: NavTokens;
-    theme: NavTheme;
-    accentColor: string;
-    menu: string | null;
-    setMenu: (menu: string | null) => void;
-    open: boolean;
-    isMobile: boolean;
-    isPeeking: boolean;
-    peekable: boolean;
-    resizable: boolean;
-    width: number;
-    mobileBreakpoint: number;
-    setOpen: (open: boolean) => void;
-    toggle: () => void;
-    close: () => void;
-    setPeeking: (peeking: boolean) => void;
-    setWidth: (width: number) => void;
-    scrollToItem: (itemId: string) => void;
-};
-export type NavProviderProps = PropsWithChildren<{
-    value?: NavValue;
-    tokens?: NavTokens;
-    theme?: NavTheme;
-    accentColor?: string;
-    defaultOpen?: boolean;
-    mobileBreakpoint?: number;
-    peekable?: boolean;
-    resizable?: boolean;
-}>;
-export declare function NavProvider({ children, value: data, tokens, theme, accentColor, defaultOpen, mobileBreakpoint, peekable, resizable, }: NavProviderProps): import("react").JSX.Element;
-export declare function useNav(): NavContextValue;

package/packages/agentsam-nav/dist/NavTrigger.d.ts

@@ -1,2 +0,0 @@
-import type { ButtonHTMLAttributes } from 'react';
-export declare function NavTrigger({ className, 'aria-label': ariaLabel, ...props }: ButtonHTMLAttributes<HTMLButtonElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/Surfaces.d.ts

@@ -1,41 +0,0 @@
-import { type CSSProperties, type HTMLAttributes, type ReactNode } from 'react';
-import type { NavAccount, NavAction } from './contracts.js';
-export declare function useNavStyle(): CSSProperties;
-export declare function NavScope({ className, style, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;
-/** The portal carries its own theme, so standalone surfaces never depend on body CSS. */
-export declare function NavOverflowMenu({ label, actions, children, id: suppliedId, align }: {
-    label?: string;
-    actions?: NavAction[];
-    children?: ReactNode;
-    id?: string;
-    align?: 'start' | 'center' | 'end';
-}): import("react").JSX.Element;
-export declare function NavTopbarLogo({ variant, onClick, toggle }: {
-    variant?: 'mark' | 'expanded';
-    onClick?: () => void;
-    toggle?: boolean;
-}): import("react").JSX.Element;
-export declare function NavProjectContext(): import("react").JSX.Element;
-export declare function NavTopbarSpacer(): import("react").JSX.Element;
-export declare function NavFilesResources(): import("react").JSX.Element;
-export declare function NavPinnedSummary(): import("react").JSX.Element | null;
-export declare function NavConversationActions(): import("react").JSX.Element;
-export declare function NavShareButton(): import("react").JSX.Element | null;
-export declare function NavAccountSwitcher({ accounts, activeAccountId, onAccountChange, expanded }: {
-    accounts?: NavAccount[];
-    activeAccountId?: string;
-    onAccountChange?: (id: string) => void;
-    expanded?: boolean;
-}): import("react").JSX.Element;
-export declare function NavModeSwitcher(): import("react").JSX.Element;
-export declare function NavTopbar({ children, rightSlot, modeSlot, contextSlot, startup, className, showNavigationTrigger, showAccount, }: {
-    children?: ReactNode;
-    rightSlot?: ReactNode;
-    modeSlot?: ReactNode;
-    contextSlot?: ReactNode;
-    startup?: boolean;
-    className?: string;
-    showNavigationTrigger?: boolean;
-    showAccount?: boolean;
-}): import("react").JSX.Element;
-export declare function NavSidenav(): import("react").JSX.Element;