@inneranimalmedia/agentsam-sdk 2.6.8 → 2.6.10

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/models/catalog.js

@@ -7,7 +7,6 @@ const DOCS = Object.freeze({
   gpt56Sol: 'https://developers.openai.com/api/docs/models/gpt-5.6-sol',
   gpt56Terra: 'https://developers.openai.com/api/docs/models/gpt-5.6-terra',
   gpt56Luna: 'https://developers.openai.com/api/docs/models/gpt-5.6-luna',
-  gpt53Codex: 'https://developers.openai.com/api/docs/models/gpt-5.3-codex',
   embeddingLarge: 'https://developers.openai.com/api/docs/models/text-embedding-3-large',
   embeddingSmall: 'https://developers.openai.com/api/docs/models/text-embedding-3-small',
 });
@@ -226,53 +225,6 @@ const GPT_56_LUNA = openAiAgentModel({
   pricing: freezePricing({ input: 0.2, cachedInput: 0.02, cacheWrite: 0.25, output: 1.2, source: DOCS.gpt56Luna }),
 });
 
-const GPT_53_CODEX = openAiAgentModel({
-  id: 'gpt-5.3-codex',
-  label: 'GPT-5.3-Codex',
-  source: DOCS.gpt53Codex,
-  reasoning: ['low', 'medium', 'high', 'xhigh'],
-  contextWindow: 400_000,
-  maxOutputTokens: 128_000,
-  knowledgeCutoff: '2025-08-31',
-  description: 'Agentic coding model for Codex-style software workflows.',
-  pricing: freezePricing({
-    input: 1.75,
-    cachedInput: 0.175,
-    cacheWrite: 0,
-    output: 14,
-    source: DOCS.gpt53Codex,
-    longContext: false,
-    processing: false,
-  }),
-  capabilities: {
-    web_search: false,
-    file_search: false,
-    image_generation: false,
-    code_interpreter: false,
-    hosted_shell: false,
-    apply_patch: false,
-    skills: false,
-    computer_use: false,
-    mcp: false,
-    tool_search: false,
-    async_tool_calls: false,
-    mid_turn_steering: false,
-    configuration_update: false,
-    fast: false,
-    flex: false,
-  },
-  serviceTiers: ['default'],
-  contextPolicy: Object.freeze({
-    target_input_tokens: 100_000,
-    compact_at_tokens: 160_000,
-    intervene_at_tokens: 210_000,
-    max_normal_input_tokens: 240_000,
-    pricing_threshold_tokens: null,
-    max_cumulative_input_tokens: 400_000,
-    safety_margin_tokens: 20_000,
-  }),
-});
-
 const TEXT_EMBEDDING_3_LARGE = openAiEmbeddingModel({
   id: 'text-embedding-3-large',
   label: 'text-embedding-3-large',
@@ -296,7 +248,6 @@ export const MODEL_CATALOG = Object.freeze([
   GPT_56_LUNA,
   GPT_56_TERRA,
   GPT_56_SOL,
-  GPT_53_CODEX,
   TEXT_EMBEDDING_3_LARGE,
   TEXT_EMBEDDING_3_SMALL,
 ]);

package/src/models/inventory-core.js

@@ -24,6 +24,75 @@ export const WORKERS_AI_CURATED_MODEL_IDS = Object.freeze([
 ]);
 
 const CURATED = new Set(WORKERS_AI_CURATED_MODEL_IDS);
+export const PROVIDER_MODEL_SNAPSHOT_SCHEMA = 'agentsam.provider-model-snapshot.v1';
+
+function modelSnapshotHash(modelIds) {
+  const source = modelIds.join('\n');
+  let hash = 2166136261;
+  for (let index = 0; index < source.length; index += 1) {
+    hash ^= source.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return `fnv1a32:${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+
+/**
+ * Compact credential-scoped availability evidence for an existing
+ * `agentsam_plugins` AI installation. The global catalog remains curated
+ * reference data; discovery never creates one model row per user.
+ */
+export function createProviderModelSnapshot(provider, models = [], options = {}) {
+  const providerId = String(provider || '').trim().toLowerCase();
+  if (!providerId) throw new TypeError('provider_required');
+  const modelIds = [...new Set(models.map((row) => String(
+    typeof row === 'string' ? row : row?.provider_model_id || row?.model_id || '',
+  ).trim()).filter(Boolean))].sort();
+  const fetchedAtUnix = Number.isFinite(Number(options.fetchedAtUnix))
+    ? Math.max(0, Math.floor(Number(options.fetchedAtUnix)))
+    : Math.floor(Date.now() / 1000);
+  return Object.freeze({
+    schema: PROVIDER_MODEL_SNAPSHOT_SCHEMA,
+    provider: providerId,
+    model_ids: Object.freeze(modelIds),
+    model_count: modelIds.length,
+    models_hash: modelSnapshotHash(modelIds),
+    fetched_at_unix: fetchedAtUnix,
+    authority: 'credential_scoped_provider_discovery',
+  });
+}
+
+/**
+ * Produce fields for the existing `agentsam_plugins` row. Failed probes keep
+ * the last good snapshot while updating health evidence; no secret or model
+ * catalog rows are written.
+ */
+export function createAiPluginProbePatch(previousMetadata = {}, discovery = {}, options = {}) {
+  const now = Number.isFinite(Number(options.fetchedAtUnix))
+    ? Math.max(0, Math.floor(Number(options.fetchedAtUnix)))
+    : Math.floor(Date.now() / 1000);
+  const metadata = previousMetadata && typeof previousMetadata === 'object' && !Array.isArray(previousMetadata)
+    ? { ...previousMetadata }
+    : {};
+  if (discovery.ok === true) {
+    metadata.model_snapshot = createProviderModelSnapshot(
+      options.provider || discovery.provider,
+      discovery.models || [],
+      { fetchedAtUnix: now },
+    );
+  }
+  const error = String(discovery.error || '').trim();
+  const authFailure = /\b(?:401|403)\b|unauthoriz|forbidden|invalid[_ -]?(?:api[_ -]?)?key|credential.*reject/i.test(error);
+  return Object.freeze({
+    metadata,
+    health_status: discovery.ok === true ? 'healthy' : authFailure ? 'auth_error' : 'unreachable',
+    last_health_at: now,
+    ...(discovery.ok === true ? { last_healthy_at: now, consecutive_failures: 0, last_error_code: null, last_error_message: null } : {
+      consecutive_failures_delta: 1,
+      last_error_code: authFailure ? 'provider_credential_rejected' : 'provider_discovery_failed',
+      last_error_message: authFailure ? 'Provider credential rejected' : 'Provider model discovery failed',
+    }),
+  });
+}
 
 const SERVICE_TO_PROVIDER = Object.freeze({
   openai: 'openai',

package/src/plugins/index.js

@@ -5,7 +5,14 @@ export {
   INNERANIMALMEDIA_CLOUDFLARE_OAUTH_PLUGIN_MANIFEST,
 } from './cloudflare.js';
 export { COMPLETEFUL_PLUGIN_MANIFEST } from './completeful.js';
-export { installPlugin, listPlugins, listPluginTools, recordPluginHealthCheck, recordToolCall } from './registry.js';
+export {
+  installPlugin,
+  listPlugins,
+  listPluginTools,
+  recordPluginHealthCheck,
+  recordAiPluginModelDiscovery,
+  recordToolCall,
+} from './registry.js';
 export { createPluginRuntime, createPluginCapabilityAdapter, executeAgentSamTool } from './runtime.js';
 export { resolveProjectPluginScope, resolveProjectPluginResources, resolveProjectRuntimeResources, resolveProjectVectorizeScope } from './resource-scope.js';
 export { resolveVectorizeConfig, executeVectorizeTool } from './vectorize.js';