@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/src/providers/openai-responses.js

@@ -0,0 +1,275 @@
+import { calculateModelCost, getModelRecord } from '../models/index.js';
+import { createAgentEvent, createUsageSnapshot } from '../telemetry/index.js';
+import { createOpenAIHttpError, diagnosticFromError } from '../errors/index.js';
+
+const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function integer(value) { const n = Number(value ?? 0); return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0; }
+
+function normalizeServiceTier(value, requested = 'default') {
+  const tier = clean(value).toLowerCase();
+  if (tier === 'priority') return 'fast';
+  if (tier === 'auto' || !tier) return requested === 'auto' ? 'default' : requested;
+  return tier;
+}
+
+export function extractOpenAIOutputText(response = {}) {
+  if (typeof response.output_text === 'string') return response.output_text;
+  const chunks = [];
+  for (const item of response.output || []) {
+    if (item?.type !== 'message') continue;
+    for (const content of item.content || []) {
+      if (content?.type === 'output_text' && typeof content.text === 'string') chunks.push(content.text);
+    }
+  }
+  return chunks.join('');
+}
+
+export function extractOpenAIFunctionCalls(response = {}) {
+  return (response.output || []).filter((item) => item?.type === 'function_call').map((item) => Object.freeze({
+    id: item.id || null,
+    call_id: item.call_id,
+    name: item.name,
+    arguments: item.arguments || '{}',
+    status: item.status || null,
+  }));
+}
+
+function usageParts(response = {}) {
+  const usage = response.usage || {};
+  return {
+    input_tokens: integer(usage.input_tokens),
+    cached_input_tokens: integer(usage.input_tokens_details?.cached_tokens),
+    cache_write_tokens: integer(usage.input_tokens_details?.cache_write_tokens),
+    output_tokens: integer(usage.output_tokens),
+    reasoning_tokens: integer(usage.output_tokens_details?.reasoning_tokens),
+  };
+}
+
+function errorMessage(body, status) {
+  return body?.error?.message || body?.message || `OpenAI Responses API returned HTTP ${status}`;
+}
+
+function optionalSignal(timeoutMs) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return undefined;
+  if (typeof AbortSignal?.timeout !== 'function') return undefined;
+  return AbortSignal.timeout(Math.floor(timeoutMs));
+}
+
+function normalizeTools(tools = []) {
+  if (!Array.isArray(tools)) throw new TypeError('tools must be an array');
+  return tools.map((tool) => {
+    if (tool?.type !== 'function' || !clean(tool.name)) throw new TypeError('OpenAI adapter tools must be Responses function tool descriptors');
+    return {
+      type: 'function',
+      name: clean(tool.name),
+      description: clean(tool.description) || undefined,
+      parameters: tool.parameters || { type: 'object', properties: {} },
+      strict: tool.strict !== false,
+      ...(tool.async === true ? { async: true } : {}),
+    };
+  });
+}
+
+function assertRuntimeConfig(model, reasoningEffort, serviceTier) {
+  const record = getModelRecord(model);
+  if (!record || record.provider !== 'openai') throw new RangeError(`unsupported OpenAI model catalog entry: ${model}`);
+  if (!record.reasoning_efforts.includes(reasoningEffort)) throw new RangeError(`unsupported reasoning effort for ${record.provider_model_id}: ${reasoningEffort}`);
+  if (!record.service_tiers.includes(serviceTier)) throw new RangeError(`unsupported service tier for ${record.provider_model_id}: ${serviceTier}`);
+  return record;
+}
+
+function emitEvent(emit, type, payload, meta = {}) {
+  if (typeof emit !== 'function') return;
+  emit(createAgentEvent(type, payload, meta));
+}
+
+export function createOpenAIResponsesAdapter(options = {}) {
+  const apiKey = clean(options.apiKey || process.env.OPENAI_API_KEY);
+  const baseUrl = clean(options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+  const fetchImpl = options.fetchImpl || fetch;
+  const defaultEmit = options.emit;
+  const timeoutMs = options.timeoutMs;
+
+  async function request(pathname, body, runtime = {}) {
+    if (!apiKey) throw new Error('OPENAI_API_KEY is required for OpenAI Responses execution');
+    const response = await fetchImpl(`${baseUrl}${pathname}`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: optionalSignal(runtime.timeoutMs ?? timeoutMs),
+    });
+    let rawText = '';
+    let parsed = null;
+    if (typeof response.text === 'function') {
+      try { rawText = await response.text(); } catch { rawText = ''; }
+      if (rawText) {
+        try { parsed = JSON.parse(rawText); } catch { parsed = null; }
+      }
+    } else if (typeof response.json === 'function') {
+      try {
+        parsed = await response.json();
+        rawText = JSON.stringify(parsed ?? null);
+      } catch {
+        parsed = null;
+        rawText = '';
+      }
+    }
+    if (!response.ok) {
+      throw createOpenAIHttpError({
+        status: response.status,
+        body: parsed,
+        rawText,
+        headers: response.headers,
+        requestedServiceTier: body?.service_tier,
+      });
+    }
+    return Object.freeze({
+      data: parsed ?? {},
+      http: Object.freeze({
+        status: response.status,
+        request_id: clean(response.headers?.get?.('x-request-id') || response.headers?.get?.('openai-request-id')) || null,
+        ray_id: clean(response.headers?.get?.('cf-ray')) || null,
+      }),
+    });
+  }
+
+  async function create(params = {}) {
+    const modelRecord = getModelRecord(params.model);
+    const model = modelRecord?.provider_model_id || clean(params.model);
+    const reasoningEffort = clean(params.reasoningEffort || params.reasoning_effort || 'low');
+    const serviceTier = clean(params.serviceTier || params.service_tier || 'default');
+    const record = assertRuntimeConfig(model, reasoningEffort, serviceTier);
+    const emit = params.emit || defaultEmit;
+    const meta = { runId: params.runId, sequence: params.sequence };
+    const tools = normalizeTools(params.tools || []);
+    const body = {
+      model,
+      input: params.input ?? '',
+      reasoning: { effort: reasoningEffort },
+      service_tier: serviceTier,
+      store: params.store !== false,
+      truncation: 'disabled',
+      parallel_tool_calls: params.parallelToolCalls !== false,
+      ...(clean(params.instructions) ? { instructions: String(params.instructions) } : {}),
+      ...(tools.length ? { tools } : {}),
+      ...(clean(params.previousResponseId) ? { previous_response_id: clean(params.previousResponseId) } : {}),
+      ...(Number.isInteger(params.maxOutputTokens) && params.maxOutputTokens > 0 ? { max_output_tokens: params.maxOutputTokens } : {}),
+      ...(clean(params.promptCacheKey) ? { prompt_cache_key: clean(params.promptCacheKey) } : {}),
+      ...(params.promptCacheOptions ? { prompt_cache_options: params.promptCacheOptions } : {}),
+      ...(params.metadata ? { metadata: params.metadata } : {}),
+      ...(params.background === true ? { background: true } : {}),
+    };
+
+    emitEvent(emit, 'model.started', {
+      provider: 'openai', model, reasoning_effort: reasoningEffort, requested_service_tier: serviceTier,
+    }, meta);
+
+    let response;
+    let http;
+    try {
+      const result = await request('/responses', body, params);
+      response = result.data;
+      http = result.http;
+    } catch (error) {
+      const diagnostic = diagnosticFromError(error, { source: 'openai', kind: 'provider_error' });
+      emitEvent(emit, 'error.observed', diagnostic, meta);
+      emitEvent(emit, 'run.failed', { stage: 'model', provider: 'openai', model, error: diagnostic }, meta);
+      throw error;
+    }
+
+    const delta = usageParts(response);
+    const actualServiceTier = normalizeServiceTier(response.service_tier, serviceTier);
+    const cost = calculateModelCost(record, { ...delta, estimate_kind: 'provider' }, { serviceTier: actualServiceTier });
+    const usageSnapshot = createUsageSnapshot({
+      current_context: { input_tokens: delta.input_tokens, window_tokens: record.context_window },
+      cumulative: params.cumulativeUsage ? {
+        input_tokens: integer(params.cumulativeUsage.input_tokens) + delta.input_tokens,
+        output_tokens: integer(params.cumulativeUsage.output_tokens) + delta.output_tokens,
+        cached_input_tokens: integer(params.cumulativeUsage.cached_input_tokens) + delta.cached_input_tokens,
+        cache_write_tokens: integer(params.cumulativeUsage.cache_write_tokens) + delta.cache_write_tokens,
+        reasoning_tokens: integer(params.cumulativeUsage.reasoning_tokens) + delta.reasoning_tokens,
+      } : delta,
+      estimate_kind: 'provider',
+    });
+
+    emitEvent(emit, 'usage.snapshot', usageSnapshot, meta);
+    emitEvent(emit, 'cost.snapshot', cost, meta);
+    emitEvent(emit, 'model.completed', {
+      provider: 'openai', model, response_id: response.id, status: response.status,
+      request_id: http?.request_id || null, ray_id: http?.ray_id || null,
+      requested_service_tier: serviceTier, actual_service_tier: actualServiceTier,
+    }, meta);
+
+    return Object.freeze({
+      provider: 'openai',
+      model,
+      response_id: response.id,
+      status: response.status,
+      request_id: http?.request_id || null,
+      ray_id: http?.ray_id || null,
+      output_text: extractOpenAIOutputText(response),
+      tool_calls: Object.freeze(extractOpenAIFunctionCalls(response)),
+      usage_delta: Object.freeze(delta),
+      usage_snapshot: usageSnapshot,
+      cost,
+      requested_service_tier: serviceTier,
+      actual_service_tier: actualServiceTier,
+      raw: response,
+    });
+  }
+
+  async function continueWithToolOutputs(params = {}) {
+    const previousResponseId = clean(params.previousResponseId);
+    if (!previousResponseId) throw new TypeError('previousResponseId is required');
+    const outputs = (params.toolOutputs || []).map((row) => {
+      const callId = clean(row.call_id || row.callId);
+      if (!callId) throw new TypeError('tool output call_id is required');
+      const output = typeof row.output === 'string' ? row.output : JSON.stringify(row.output ?? null);
+      return { type: 'function_call_output', call_id: callId, output };
+    });
+    if (!outputs.length) throw new TypeError('at least one tool output is required');
+    return create({ ...params, previousResponseId, input: outputs });
+  }
+
+  async function compact(params = {}) {
+    const modelRecord = getModelRecord(params.model);
+    const model = modelRecord?.provider_model_id || clean(params.model);
+    if (!modelRecord || modelRecord.provider !== 'openai') throw new RangeError(`unsupported OpenAI model catalog entry: ${params.model}`);
+    const emit = params.emit || defaultEmit;
+    const meta = { runId: params.runId, sequence: params.sequence };
+    const body = {
+      model,
+      ...(clean(params.previousResponseId) ? { previous_response_id: clean(params.previousResponseId) } : {}),
+      ...(params.input != null ? { input: params.input } : {}),
+      ...(clean(params.instructions) ? { instructions: String(params.instructions) } : {}),
+      ...(clean(params.promptCacheKey) ? { prompt_cache_key: clean(params.promptCacheKey) } : {}),
+      ...(params.promptCacheOptions ? { prompt_cache_options: params.promptCacheOptions } : {}),
+    };
+    emitEvent(emit, 'context.compaction.started', { provider: 'openai', model, previous_response_id: body.previous_response_id || null }, meta);
+    let response;
+    let http;
+    try {
+      const result = await request('/responses/compact', body, params);
+      response = result.data;
+      http = result.http;
+    } catch (error) {
+      const diagnostic = diagnosticFromError(error, { source: 'openai', kind: 'provider_error' });
+      emitEvent(emit, 'error.observed', diagnostic, meta);
+      emitEvent(emit, 'run.failed', { stage: 'compaction', provider: 'openai', model, error: diagnostic }, meta);
+      throw error;
+    }
+    emitEvent(emit, 'context.compaction.completed', {
+      provider: 'openai', model, compaction_id: response.id, usage: response.usage || null,
+      request_id: http?.request_id || null, ray_id: http?.ray_id || null,
+    }, meta);
+    return Object.freeze({
+      provider: 'openai', model, compaction_id: response.id,
+      request_id: http?.request_id || null, ray_id: http?.ray_id || null,
+      output: Object.freeze(response.output || []), usage: response.usage || null, raw: response,
+    });
+  }
+
+  return Object.freeze({ provider: 'openai', create, continueWithToolOutputs, compact });
+}

package/src/security/index.js

@@ -4,3 +4,4 @@ export { triageLog, resolveLogFindings } from './logs.js';
 export { scanProjectSecurity, remediationPlan, reportExitCode } from './scan.js';
 export { repairProject } from './repair.js';
 export { formatSecurityReport } from './render.js';
+export { scanTrustBoundary } from './trust-boundary.js';

package/src/security/inventory.js

@@ -76,7 +76,10 @@ export function collectNpmDependencies(projectRoot = process.cwd()) {
         if (location) {
           const workspacePath = path.resolve(root, location);
           const relative = path.relative(root, fs.realpathSync(workspacePath));
-          if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('Workspace escapes project root');
+          if (relative.startsWith('..') || path.isAbsolute(relative)) {
+            issues.push('Linked package escapes project root and cannot be fully verified here: ' + location);
+            continue;
+          }
           const workspace = readJson(path.join(workspacePath, 'package.json'));
           for (const field of fields) {
             if (JSON.stringify(Object.entries(workspace[field] || {}).sort()) !== JSON.stringify(Object.entries(pkg[field] || {}).sort())) issues.push('Workspace manifest and lockfile disagree: ' + location + ':' + field);

package/src/security/process.js

@@ -1,31 +1,57 @@
 import { spawn } from 'node:child_process';
+import { createProcessDiagnosticError } from '../errors/index.js';
 
 export function runProcess(command, args, { cwd, timeoutMs = 300_000, signal, env = process.env, maxBytes = 8 * 1024 * 1024 } = {}) {
   return new Promise((resolve, reject) => {
-    if (signal?.aborted) return reject(new Error('Command cancelled'));
-    const child = spawn(command, args, { cwd, env, shell: false, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
+    const safeArgs = Array.isArray(args) ? args : [];
+    const diagnostic = (code, message, extra = {}) => createProcessDiagnosticError({
+      code,
+      message,
+      command,
+      args: safeArgs,
+      cwd,
+      stdout,
+      stderr,
+      ...extra,
+    });
     let stdout = '', stderr = '', size = 0, failure, hardKill;
+    if (signal?.aborted) return reject(createProcessDiagnosticError({ code: 'process_cancelled', message: 'Command cancelled', command, args: safeArgs, cwd }));
+    const child = spawn(command, safeArgs, { cwd, env, shell: false, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
     function kill(sig) {
       try { process.kill(process.platform === 'win32' ? child.pid : -child.pid, sig); } catch { /* already exited */ }
     }
-    function stop(reason) {
+    function stop(error) {
       if (failure) return;
-      failure = reason;
+      failure = error;
       kill('SIGTERM');
       hardKill = setTimeout(() => kill('SIGKILL'), 1000);
     }
-    const timer = setTimeout(() => stop('Command timed out'), timeoutMs);
-    const abort = () => stop('Command cancelled');
+    const timer = setTimeout(() => stop(diagnostic('process_timeout', 'Command timed out', { retriable: false })), timeoutMs);
+    const abort = () => stop(diagnostic('process_cancelled', 'Command cancelled'));
     signal?.addEventListener('abort', abort, { once: true });
     const receive = (key) => chunk => {
       size += chunk.length;
-      if (size > maxBytes) return stop('Command output exceeded 8 MiB');
+      if (size > maxBytes) return stop(diagnostic('process_output_limit', `Command output exceeded ${maxBytes} bytes`));
       if (key === 'stdout') stdout += chunk.toString(); else stderr += chunk.toString();
     };
     child.stdout.on('data', receive('stdout'));
     child.stderr.on('data', receive('stderr'));
     const cleanup = () => { clearTimeout(timer); clearTimeout(hardKill); signal?.removeEventListener('abort', abort); };
-    child.on('error', () => { cleanup(); reject(new Error('Cannot start requested command')); });
-    child.on('close', code => { cleanup(); failure ? reject(new Error(failure)) : resolve({ code: code ?? 1, stdout, stderr }); });
+    child.on('error', (cause) => {
+      cleanup();
+      reject(createProcessDiagnosticError({
+        code: cause?.code || 'process_spawn_failed',
+        message: cause?.message || 'Cannot start requested command',
+        command,
+        args: safeArgs,
+        cwd,
+        cause,
+      }));
+    });
+    child.on('close', (code, closeSignal) => {
+      cleanup();
+      if (failure) return reject(failure);
+      resolve({ code: code ?? 1, signal: closeSignal || null, stdout, stderr });
+    });
   });
 }

package/src/security/render.js

@@ -1,15 +1,26 @@
 import { stripVTControlCharacters } from 'node:util';
 
 export const safeText = value => stripVTControlCharacters(String(value ?? '')).replace(/[\x00-\x1f\x7f-\x9f]/g, ' ').replace(/[\u202a-\u202e\u2066-\u2069]/g, '');
+
+function renderBoundaryFinding(item, lines) {
+  const evidence = [item.kind, item.source, item.target ? `→ ${item.target}` : null, item.specifier, item.env].filter(Boolean).join(' · ');
+  lines.push('  ! ' + safeText(evidence));
+  lines.push('    Next: ' + safeText(item.action || item.repair?.action || 'review-trust-boundary'));
+  if (item.repair?.summary) lines.push('    ' + safeText(item.repair.summary));
+}
+
 export function formatSecurityReport(report, { color = false } = {}) {
   const scan = report.after || report.scan || report.before || report;
   const label = safeText(report.status || scan.status).toUpperCase();
-  const title = 'Agent Sam · dependency health · ' + label;
+  const title = 'Agent Sam · security · ' + label;
+  const boundary = scan.trust_boundary;
   const lines = [color ? '\x1b[1;36m' + title + '\x1b[0m' : title,
+    '',
+    'Dependencies',
     '  Checked: ' + scan.checked_count + '/' + scan.dependency_count + ' packages',
-    '  Coverage: ' + (scan.complete ? 'complete' : 'INCOMPLETE — not a clean bill of health')];
+    '  Coverage: ' + (scan.dependency_complete ? 'complete' : 'INCOMPLETE — dependency graph not fully verified')];
   for (const issue of scan.issues || []) lines.push('  ! ' + safeText(issue));
-  for (const item of scan.findings || []) {
+  for (const item of (scan.findings || []).filter((finding) => finding.section !== 'trust-boundary')) {
     lines.push('  ! ' + safeText([item.kind, item.package, item.version, item.advisory?.id, item.advisory?.severity].filter(Boolean).join(' · ')));
     lines.push('    Next: ' + safeText(item.action));
     if (item.advisory?.url) lines.push('    ' + safeText(item.advisory.url));
@@ -17,8 +28,19 @@ export function formatSecurityReport(report, { color = false } = {}) {
   }
   const informational = (scan.log_findings || []).filter(f => f.resolution === 'informational').length;
   if (informational) lines.push('  Informational log notices: ' + informational);
-  if (report.worktree) lines.push('  Candidate: ' + safeText(report.worktree), '  Branch: ' + safeText(report.branch));
+
+  if (boundary) {
+    lines.push('', 'Trust boundary',
+      '  AST files: ' + safeText(boundary.ast_files),
+      '  Browser graph: ' + safeText(boundary.browser_reachable_files) + ' reachable files from ' + safeText(boundary.browser_roots) + ' browser roots',
+      '  Evidence: merkle=' + safeText(boundary.merkle_root) + ' metadata=' + safeText(boundary.metadata_root),
+      '  Coverage: ' + (boundary.complete ? 'complete for indexed JS/TS syntax' : 'INCOMPLETE — parse errors prevent a clean boundary result'));
+    for (const item of boundary.findings || []) renderBoundaryFinding(item, lines);
+    if (!boundary.findings?.length) lines.push('  ✓ no indexed client/server boundary contradictions detected');
+  }
+
+  if (report.worktree) lines.push('', '  Candidate: ' + safeText(report.worktree), '  Branch: ' + safeText(report.branch));
   if (report.reason) lines.push('  Reason: ' + safeText(report.reason));
-  if (report.mode === 'plan') lines.push('  Apply in an isolated worktree: agentsam security repair --apply');
+  if (report.mode === 'plan') lines.push('  Apply dependency-only automatic repair in an isolated worktree: agentsam security repair --apply');
   return lines.join('\n') + '\n';
 }

package/src/security/scan.js

@@ -1,38 +1,53 @@
 import { collectNpmDependencies } from './inventory.js';
 import { queryOsv } from './osv.js';
 import { triageLog, resolveLogFindings } from './logs.js';
+import { scanTrustBoundary } from './trust-boundary.js';
 
 export async function scanProjectSecurity(options = {}) {
   const inventory = collectNpmDependencies(options.projectRoot);
   const results = options.offline
     ? inventory.dependencies.map(d => ({ ...d, checked: false, advisories: [] }))
     : await queryOsv(inventory.dependencies, options);
-  const complete = !options.offline && !options.signal?.aborted && !inventory.issues.length && results.every(r => r.checked);
-  const logFindings = resolveLogFindings(triageLog(options.log || ''), { complete, results });
-  const findings = [
-    ...results.flatMap(r => r.advisories.map(a => ({ kind: 'vulnerability', package: r.name, version: r.version, advisory: a, action: 'audit-fix-within-ranges' }))),
-    ...results.filter(r => r.deprecated).map(r => ({ kind: 'deprecated', package: r.name, version: r.version, action: 'update-within-ranges' })),
-    ...logFindings.filter(f => f.resolution === 'action-required'),
+  const dependencyComplete = !options.offline && !options.signal?.aborted && !inventory.issues.length && results.every(r => r.checked);
+  const scanBoundary = options.scanBoundary || scanTrustBoundary;
+  const trustBoundary = await scanBoundary(inventory.root, options);
+  const complete = dependencyComplete && trustBoundary.complete;
+  const logFindings = resolveLogFindings(triageLog(options.log || ''), { complete: dependencyComplete, results });
+  const dependencyFindings = [
+    ...results.flatMap(r => r.advisories.map(a => ({ kind: 'vulnerability', section: 'dependencies', package: r.name, version: r.version, advisory: a, action: 'audit-fix-within-ranges' }))),
+    ...results.filter(r => r.deprecated).map(r => ({ kind: 'deprecated', section: 'dependencies', package: r.name, version: r.version, action: 'update-within-ranges' })),
+    ...logFindings.filter(f => f.resolution === 'action-required').map((f) => ({ ...f, section: 'logs' })),
   ];
+  const boundaryFindings = (trustBoundary.findings || []).map((item) => ({
+    ...item,
+    section: 'trust-boundary',
+    action: item.repair?.action || 'review-trust-boundary',
+  }));
+  const findings = [...dependencyFindings, ...boundaryFindings];
   return {
     schema_version: 1, scanner: 'agentsam-sca', checked_at: new Date().toISOString(),
     project_root: inventory.root, lockfile: inventory.lockfile, lock_fingerprint: inventory.fingerprint,
     complete, status: !complete ? 'incomplete' : findings.length ? 'action-required' : 'clean',
     ok: complete && findings.length === 0,
     dependency_count: results.length, checked_count: results.filter(r => r.checked).length,
+    dependency_complete: dependencyComplete,
     issues: inventory.issues, skipped: inventory.skipped, results, findings, log_findings: logFindings,
+    trust_boundary: trustBoundary,
   };
 }
 export const reportExitCode = report => report.complete === false ? 2 : report.ok ? 0 : 1;
 export function remediationPlan(report) {
+  const boundaryRepairs = report.trust_boundary?.repair_suggestions || [];
   return {
     mode: 'plan', ok: report.ok, complete: report.complete, status: report.status,
     scan: report,
     steps: [
-      { action: 'npm-audit-fix', automatic: report.complete, constraints: 'Existing manifest ranges; no force; no lifecycle scripts during resolution.' },
-      ...(report.findings.some(f => f.kind === 'deprecated') ? [{ action: 'npm-update', automatic: report.complete, constraints: 'Existing ranges; package manifests unchanged.' }] : []),
-      { action: 'verify', automatic: report.complete, constraints: 'Fresh install, configured project verification script, advisory rescan and warning triage.' },
+      { action: 'npm-audit-fix', automatic: report.dependency_complete !== false, constraints: 'Existing manifest ranges; no force; no lifecycle scripts during resolution.' },
+      ...(report.findings.some(f => f.kind === 'deprecated') ? [{ action: 'npm-update', automatic: report.dependency_complete !== false, constraints: 'Existing ranges; package manifests unchanged.' }] : []),
+      ...boundaryRepairs.map((repair) => ({ ...repair, constraints: 'Preserve the existing public contract where possible; verify the repaired import graph against a fresh Merkle/filemeta snapshot.' })),
+      { action: 'verify', automatic: report.complete, constraints: 'Fresh install, configured project verification script, advisory rescan, warning triage, and trust-boundary rescan.' },
     ],
+    boundary_repairs: boundaryRepairs,
     manual: report.findings.filter(f => !['vulnerability', 'deprecated', 'audit'].includes(f.kind)),
   };
 }

package/src/security/trust-boundary.js

@@ -0,0 +1,24 @@
+import fs from 'node:fs';
+import { buildMerkleTree } from '../lib/merkle/index.js';
+import { gitIgnoredPaths } from '../lib/merkle/git-ignore.js';
+import { analyzeExecutionBoundaries } from '../indexing/execution-boundary.js';
+
+export async function scanTrustBoundary(projectRoot = process.cwd(), options = {}) {
+  const root = fs.realpathSync(projectRoot);
+  const ignored = options.exclude || await gitIgnoredPaths(root);
+  const snapshot = options.snapshot || await buildMerkleTree(root, { semantic: true, exclude: ignored });
+  if (!snapshot.semantic) throw new Error('Semantic Merkle metadata is required for trust-boundary scanning');
+  const analysis = analyzeExecutionBoundaries(snapshot.semantic);
+  return {
+    ...analysis,
+    project_root: root,
+    merkle_root: snapshot.rootHash,
+    metadata_root: snapshot.semantic.rootHash,
+    evidence: {
+      authority: 'agentsam-merkle+agentsam-filemeta',
+      merkle_root: snapshot.rootHash,
+      metadata_root: snapshot.semantic.rootHash,
+      policy_hash: snapshot.policyHash || null,
+    },
+  };
+}

package/src/skills/index.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const skillsRoot = path.resolve(moduleDir, '..', '..', 'skills');
+const catalogPath = path.join(skillsRoot, 'catalog.json');
+
+function readCatalog() {
+  return JSON.parse(fs.readFileSync(catalogPath, 'utf8'));
+}
+
+function normalizeSkillId(value) {
+  return String(value ?? '').trim().toLowerCase();
+}
+
+function resolveSkillRecord(idOrAlias) {
+  const needle = normalizeSkillId(idOrAlias);
+  if (!needle) return null;
+  const catalog = readCatalog();
+  return catalog.skills.find((skill) => {
+    if (normalizeSkillId(skill.id) === needle) return true;
+    return (skill.aliases ?? []).some((alias) => normalizeSkillId(alias) === needle);
+  }) ?? null;
+}
+
+function safeSkillPath(relativePath) {
+  const resolved = path.resolve(skillsRoot, relativePath);
+  const rootWithSep = `${skillsRoot}${path.sep}`;
+  if (resolved !== skillsRoot && !resolved.startsWith(rootWithSep)) {
+    throw new Error('skill_path_outside_root');
+  }
+  return resolved;
+}
+
+export function listSkills() {
+  return readCatalog().skills.map((skill) => ({ ...skill }));
+}
+
+export function getSkill(idOrAlias) {
+  const skill = resolveSkillRecord(idOrAlias);
+  return skill ? { ...skill } : null;
+}
+
+export function loadSkill(idOrAlias, options = {}) {
+  const skill = resolveSkillRecord(idOrAlias);
+  if (!skill) throw new Error(`unknown_skill:${idOrAlias}`);
+
+  const result = {
+    skill: { ...skill },
+    instructions: fs.readFileSync(safeSkillPath(skill.entry), 'utf8'),
+  };
+
+  if (options.references === true) {
+    result.references = (skill.references ?? []).map((relativePath) => ({
+      path: relativePath,
+      content: fs.readFileSync(safeSkillPath(relativePath), 'utf8'),
+    }));
+  }
+
+  return result;
+}
+
+export const AGENTSAM_SKILLS_ROOT = skillsRoot;