@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.5

package/src/mcp/client.js

@@ -1,5 +1,22 @@
+/**
+ * MCP JSON-RPC client for AgentSam CLI (ping / tools/list / tools/call).
+ *
+ * Prefers Streamable HTTP (current MCP remote transport), falls back to SSE.
+ * Does not invent connection presets — callers pass a concrete serverConfig.
+ */
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const PKG_VERSION = (() => {
+  try {
+    return require('../../package.json').version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+})();
 
 function clean(value) {
   return value == null ? '' : String(value).trim();
@@ -7,57 +24,121 @@ function clean(value) {
 
 export function buildHeaders(serverConfig = {}) {
   const headers = {
-    'Accept': 'application/json, text/event-stream',
-    'User-Agent': 'AgentSam-SDK/2.6.3 (MCP Client)',
+    Accept: 'application/json, text/event-stream',
+    'User-Agent': `AgentSam-SDK/${PKG_VERSION} (MCP Client)`,
   };
   const token = clean(serverConfig.auth?.token);
   if (token) {
-    headers['Authorization'] = `Bearer ${token}`;
+    headers.Authorization = `Bearer ${token}`;
   }
   return headers;
 }
 
+/**
+ * @template T
+ * @param {object} serverConfig
+ * @param {(client: import('@modelcontextprotocol/sdk/client/index.js').Client, transport: string) => Promise<T>} fn
+ * @param {{ timeoutMs?: number }} [options]
+ * @returns {Promise<{ ok: true, value: T, transport: string } | { ok: false, error: string, transport?: string }>}
+ */
+export async function withMcpClient(serverConfig, fn, options = {}) {
+  const url = clean(serverConfig.url);
+  if (!url) return { ok: false, error: 'missing_mcp_server_url' };
+
+  const headers = buildHeaders(serverConfig);
+  const requestInit = { headers };
+  const errors = [];
+
+  const tryTransport = async (label, createTransport) => {
+    const transport = createTransport();
+    const client = new Client(
+      { name: 'agentsam-sdk', version: PKG_VERSION },
+      { capabilities: {} },
+    );
+    const timer = setTimeout(() => {
+      try { transport.close?.(); } catch { /* ignore */ }
+    }, options.timeoutMs || 15000);
+    try {
+      await client.connect(transport);
+      const value = await fn(client, label);
+      return { ok: true, value, transport: label };
+    } finally {
+      clearTimeout(timer);
+      try { await transport.close?.(); } catch { /* ignore */ }
+    }
+  };
+
+  try {
+    return await tryTransport(
+      'streamable_http',
+      () => new StreamableHTTPClientTransport(new URL(url), { requestInit }),
+    );
+  } catch (err) {
+    errors.push(`streamable_http:${err?.message || err}`);
+  }
+
+  try {
+    return await tryTransport(
+      'sse',
+      () => new SSEClientTransport(new URL(url), { requestInit }),
+    );
+  } catch (err) {
+    errors.push(`sse:${err?.message || err}`);
+  }
+
+  return { ok: false, error: errors.join(' | ') || 'mcp_connect_failed' };
+}
+
 export async function pingMcpServer(serverConfig = {}, options = {}) {
   const url = clean(serverConfig.url);
   if (!url) throw new Error('missing_mcp_server_url');
 
   const startMs = Date.now();
-  const headers = buildHeaders(serverConfig);
-  const timeoutMs = options.timeoutMs || 5000;
+  const connected = await withMcpClient(
+    serverConfig,
+    async (client) => {
+      // listTools is a cheap post-initialize probe across CF portals
+      const tools = await client.listTools().catch(() => ({ tools: [] }));
+      return { toolCount: tools?.tools?.length ?? 0 };
+    },
+    { timeoutMs: options.timeoutMs || 8000 },
+  );
+
+  const latencyMs = Date.now() - startMs;
+  if (connected.ok) {
+    return {
+      ok: true,
+      status: 200,
+      statusText: 'connected',
+      latencyMs,
+      url,
+      transport: connected.transport,
+      toolCount: connected.value?.toolCount ?? null,
+    };
+  }
 
+  // Last-resort HTTP reachability (does not prove MCP session)
   try {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-
-    // First attempt an HTTP OPTIONS or GET / health ping
+    const headers = buildHeaders(serverConfig);
     const res = await fetch(url, {
-      method: 'GET',
-      headers,
-      signal: controller.signal,
-    }).catch(async () => {
-      // If GET returns 405/404, try POST with JSON-RPC ping
-      return await fetch(url, {
-        method: 'POST',
-        headers: { ...headers, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'ping' }),
-        signal: controller.signal,
-      });
+      method: 'POST',
+      headers: { ...headers, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'ping' }),
+      signal: AbortSignal.timeout(options.timeoutMs || 5000),
     });
-
-    clearTimeout(timer);
-    const latencyMs = Date.now() - startMs;
-
     return {
       ok: res.status < 500,
       status: res.status,
       statusText: res.statusText,
-      latencyMs,
+      latencyMs: Date.now() - startMs,
       url,
+      transport: 'http_jsonrpc_ping',
+      warning: connected.error,
     };
   } catch (err) {
     return {
       ok: false,
-      error: err.name === 'AbortError' ? 'timeout' : err.message,
+      error: connected.error || (err.name === 'TimeoutError' || err.name === 'AbortError' ? 'timeout' : err.message),
       latencyMs: Date.now() - startMs,
       url,
     };
@@ -65,108 +146,47 @@ export async function pingMcpServer(serverConfig = {}, options = {}) {
 }
 
 export async function listMcpTools(serverConfig = {}, options = {}) {
-  const url = clean(serverConfig.url);
-  if (!url) throw new Error('missing_mcp_server_url');
-
-  const headers = buildHeaders(serverConfig);
-
-  // Try standard JSON-RPC tools/list via POST first (fastest across Cloudflare Workers)
-  try {
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: { ...headers, 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        jsonrpc: '2.0',
-        id: 'tools-list-1',
-        method: 'tools/list',
-        params: {},
-      }),
-      signal: AbortSignal.timeout(options.timeoutMs || 8000),
-    });
-
-    if (res.ok) {
-      const data = await res.json();
-      if (data?.result?.tools && Array.isArray(data.result.tools)) {
-        return {
-          tools: data.result.tools,
-          count: data.result.tools.length,
-          transport: 'http_jsonrpc',
-        };
-      }
-    }
-  } catch {
-    // Fall back to SSE transport below
-  }
-
-  // Fallback to SSE transport via @modelcontextprotocol/sdk
-  try {
-    const transport = new SSEClientTransport(new URL(url), {
-      requestInit: { headers },
-    });
-    const client = new Client({ name: 'agentsam-sdk', version: '2.6.3' }, { capabilities: {} });
-    await client.connect(transport);
-    const toolsResult = await client.listTools();
-    await transport.close();
-
+  const connected = await withMcpClient(
+    serverConfig,
+    async (client) => client.listTools(),
+    { timeoutMs: options.timeoutMs || 12000 },
+  );
+
+  if (connected.ok) {
+    const tools = connected.value?.tools || [];
     return {
-      tools: toolsResult.tools || [],
-      count: toolsResult.tools?.length || 0,
-      transport: 'sse_sdk',
-    };
-  } catch (err) {
-    return {
-      tools: [],
-      count: 0,
-      error: err.message,
+      tools,
+      count: tools.length,
+      transport: connected.transport,
     };
   }
+
+  return {
+    tools: [],
+    count: 0,
+    error: connected.error,
+  };
 }
 
 export async function callMcpTool(serverConfig = {}, toolName, args = {}, options = {}) {
-  const url = clean(serverConfig.url);
-  if (!url) throw new Error('missing_mcp_server_url');
-
   const startMs = Date.now();
-  const headers = buildHeaders(serverConfig);
-
-  try {
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: { ...headers, 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        jsonrpc: '2.0',
-        id: `call-${Date.now()}`,
-        method: 'tools/call',
-        params: {
-          name: toolName,
-          arguments: args,
-        },
-      }),
-      signal: AbortSignal.timeout(options.timeoutMs || 30000),
-    });
-
-    const latencyMs = Date.now() - startMs;
-    if (!res.ok) {
-      return {
-        ok: false,
-        status: res.status,
-        error: `HTTP ${res.status}: ${res.statusText}`,
-        latencyMs,
-      };
-    }
-
-    const data = await res.json();
-    return {
-      ok: !data.error && !data.result?.isError,
-      result: data.result,
-      error: data.error?.message || (data.result?.isError ? JSON.stringify(data.result.content) : null),
-      latencyMs,
-    };
-  } catch (err) {
-    return {
-      ok: false,
-      error: err.message,
-      latencyMs: Date.now() - startMs,
-    };
+  const connected = await withMcpClient(
+    serverConfig,
+    async (client) => client.callTool({ name: toolName, arguments: args }),
+    { timeoutMs: options.timeoutMs || 30000 },
+  );
+
+  const latencyMs = Date.now() - startMs;
+  if (!connected.ok) {
+    return { ok: false, error: connected.error, latencyMs };
   }
+
+  const result = connected.value;
+  return {
+    ok: !result?.isError,
+    result,
+    error: result?.isError ? JSON.stringify(result.content) : null,
+    latencyMs,
+    transport: connected.transport,
+  };
 }

package/src/mcp/cloudflare-bundles.js

@@ -0,0 +1,225 @@
+/**
+ * Cloudflare-hosted MCP portal servers (tool bundles), not OAuth clients.
+ *
+ * Each entry is an MCP *server* you can register with `agentsam mcp add <name>`.
+ * OAuth consent stays granular via feature packs / capability ids — never the
+ * full ~315-scope catalog. Managing portals themselves needs mcp-portals.*.
+ */
+
+import {
+  scopesForCapabilities,
+  scopesForFeaturePacks,
+} from '../../packages/connectors/cloudflare/src/capabilities.js';
+
+/**
+ * @typedef {object} CloudflareMcpBundle
+ * @property {string} name
+ * @property {string} display_name
+ * @property {string} url
+ * @property {'none'|'bearer'|'cloudflare_portal_oauth'|'user_oauth_cloudflare'} auth_type
+ * @property {'streamable_http'|'sse'} protocol
+ * @property {string[]} feature_packs — AgentSam CF feature pack ids for AgentSam-side upgrade
+ * @property {string[]} capability_ids — finer granulation than packs
+ * @property {string[]} portal_manage_scopes — scopes to create/manage this portal via CF API
+ * @property {string} description
+ */
+
+/** @type {readonly CloudflareMcpBundle[]} */
+export const CLOUDFLARE_MCP_SERVER_BUNDLES = Object.freeze([
+  {
+    name: 'cloudflare-api',
+    display_name: 'Cloudflare API (Code Mode)',
+    url: 'https://mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: [],
+    capability_ids: [],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Full CF API via search/execute tools — Cloudflare hosts OAuth for this portal',
+  },
+  {
+    name: 'cloudflare-docs',
+    display_name: 'Cloudflare Docs',
+    url: 'https://docs.mcp.cloudflare.com/mcp',
+    auth_type: 'none',
+    protocol: 'streamable_http',
+    feature_packs: [],
+    capability_ids: [],
+    portal_manage_scopes: ['mcp-portals.read'],
+    description: 'Cloudflare developer documentation reference',
+  },
+  {
+    name: 'cloudflare-bindings',
+    display_name: 'Cloudflare Workers Bindings',
+    url: 'https://bindings.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['data', 'compute', 'ai'],
+    capability_ids: [
+      'cloudflare.workers',
+      'cloudflare.d1',
+      'cloudflare.kv',
+      'cloudflare.r2',
+      'cloudflare.workers_ai',
+    ],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Workers storage, AI, and compute bindings',
+  },
+  {
+    name: 'cloudflare-builds',
+    display_name: 'Cloudflare Workers Builds',
+    url: 'https://builds.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['compute'],
+    capability_ids: ['cloudflare.workers'],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Workers Builds / CI insights (workers-ci.*)',
+  },
+  {
+    name: 'cloudflare-observability',
+    display_name: 'Cloudflare Observability',
+    url: 'https://observability.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['compute'],
+    capability_ids: ['cloudflare.workers'],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Workers observability / logs / analytics',
+  },
+  {
+    name: 'cloudflare-browser',
+    display_name: 'Cloudflare Browser Rendering',
+    url: 'https://browser.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['compute'],
+    capability_ids: ['cloudflare.browser_rendering'],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Fetch pages, markdown, screenshots',
+  },
+  {
+    name: 'cloudflare-logs',
+    display_name: 'Cloudflare Logpush',
+    url: 'https://logs.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['analytics'],
+    capability_ids: [],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Logpush job health',
+  },
+  {
+    name: 'cloudflare-ai-gateway',
+    display_name: 'Cloudflare AI Gateway',
+    url: 'https://ai-gateway.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['ai'],
+    capability_ids: ['cloudflare.workers_ai'],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'AI Gateway request logs',
+  },
+  {
+    name: 'cloudflare-audit-logs',
+    display_name: 'Cloudflare Audit Logs',
+    url: 'https://auditlogs.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['analytics'],
+    capability_ids: [],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Account audit log reports',
+  },
+  {
+    name: 'cloudflare-dns-analytics',
+    display_name: 'Cloudflare DNS Analytics',
+    url: 'https://dns-analytics.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['dns', 'analytics'],
+    capability_ids: [],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'DNS performance analytics',
+  },
+  {
+    name: 'cloudflare-graphql',
+    display_name: 'Cloudflare GraphQL',
+    url: 'https://graphql.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['analytics'],
+    capability_ids: [],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Analytics via GraphQL',
+  },
+  {
+    name: 'cloudflare-containers',
+    display_name: 'Cloudflare Container Sandbox',
+    url: 'https://containers.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['compute'],
+    capability_ids: ['cloudflare.containers'],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Ephemeral sandboxed containers',
+  },
+]);
+
+export function listCloudflareMcpBundles() {
+  return [...CLOUDFLARE_MCP_SERVER_BUNDLES];
+}
+
+export function getCloudflareMcpBundle(name) {
+  const key = String(name || '').trim().toLowerCase();
+  if (!key) return null;
+  return CLOUDFLARE_MCP_SERVER_BUNDLES.find((b) => b.name === key) || null;
+}
+
+/**
+ * Scopes AgentSam should request (or upgrade) so a CF-connected user can
+ * manage / use the portal surface — not Cloudflare's own portal OAuth dance.
+ */
+export function scopesForCloudflareMcpBundle(name, options = {}) {
+  const bundle = getCloudflareMcpBundle(name);
+  if (!bundle) return [];
+
+  const set = new Set();
+  if (options.includePortalManage !== false) {
+    for (const s of bundle.portal_manage_scopes || []) set.add(s);
+  }
+  for (const s of scopesForFeaturePacks(bundle.feature_packs || [], bundle.capability_ids || [])) {
+    set.add(s);
+  }
+  if (options.includeBaseline === false) {
+    // scopesForFeaturePacks always includes baseline; strip if caller asks
+    for (const s of ['account-settings.read', 'user-details.read', 'memberships.read', 'offline_access']) {
+      // keep offline_access — refresh still needed
+      if (s !== 'offline_access') set.delete(s);
+    }
+  }
+  return [...set];
+}
+
+/** Catalog rows for MCP authority (server presets). */
+export function cloudflareBundlesAsServerCatalog() {
+  return CLOUDFLARE_MCP_SERVER_BUNDLES.map((b) => ({
+    name: b.name,
+    display_name: b.display_name,
+    url: b.url,
+    auth_type: b.auth_type,
+    protocol: b.protocol,
+    defaultClients: ['cursor'],
+    health_status: 'unknown',
+    avg_latency_ms: null,
+    error_rate: null,
+    description: b.description,
+    feature_packs: b.feature_packs,
+    capability_ids: b.capability_ids,
+    portal_manage_scopes: b.portal_manage_scopes,
+    provider: 'cloudflare',
+    kind: 'mcp_portal_bundle',
+  }));
+}
+
+export { scopesForCapabilities, scopesForFeaturePacks };

package/src/mcp/index.js

@@ -22,6 +22,8 @@ export {
   DEFAULT_CLIENT_REGISTRY_URL,
   CLIENT_REGISTRY_CACHE_SCHEMA,
   SEED_EXTERNAL_CLIENT_REGISTRY,
+  SEED_OFFERABLE_MCP_SERVER_CONNECTIONS,
+  listOfferableMcpServerConnections,
   fetchExternalClientRegistry,
   listRegisteredClients,
   isClientRegistered,
@@ -37,8 +39,18 @@ export {
   pingMcpServer,
   listMcpTools,
   callMcpTool,
+  withMcpClient,
+  buildHeaders,
 } from './client.js';
 
+export {
+  CLOUDFLARE_MCP_SERVER_BUNDLES,
+  listCloudflareMcpBundles,
+  getCloudflareMcpBundle,
+  scopesForCloudflareMcpBundle,
+  cloudflareBundlesAsServerCatalog,
+} from './cloudflare-bundles.js';
+
 export {
   recordToolReceipt,
   getSessionToolReceipts,

package/src/plugins/cloudflare.js

@@ -19,7 +19,7 @@ export const AGENTSAM_MCP_PLUGIN_MANIFEST = normalizePluginManifest({
     { capability_key: 'cloudflare.api.execute', domain: 'cloudflare', verb: 'execute', description: 'Execute a bounded Cloudflare API Code Mode program.', is_mutating: true },
   ],
   tool_lanes: ['typed', 'mcp', 'api', 'codemode'],
-  resource_scope: { owner: 'account', oauth_connection_table: 'agentsam_cloudflare_connections' },
+  resource_scope: { owner: 'account', oauth_connection_table: 'user_oauth_tokens' },
   config: {
     oauth_authority: 'cloudflare',
     oauth_client_id: 'c0704bd7a7aab7216b362603e1985499',

package/src/providers/ollama-chat.js

@@ -1,5 +1,6 @@
 import { createAgentEvent, createUsageSnapshot } from '../telemetry/index.js';
 import { diagnosticFromError } from '../errors/index.js';
+import { resolveOllamaEndpoint } from '../../packages/agentsam-knowledge/src/providers/ollama-endpoint.js';
 
 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; }
@@ -28,7 +29,7 @@ function callsFromMessage(message = {}) {
 
 export function createOllamaChatAdapter(options = {}) {
   const fetchImpl = options.fetchImpl || fetch;
-  const endpoint = clean(options.endpoint || process.env.OLLAMA_BASE_URL || 'http://127.0.0.1:11434').replace(/\/$/, '');
+  const endpoint = resolveOllamaEndpoint({ endpoint: options.endpoint, env: options.env || process.env });
 
   async function send(messages, params = {}) {
     const record = params.modelRecord || options.modelRecord;

package/src/sam/types.js

@@ -6,13 +6,34 @@
 export const SAM_RESULT_SCHEMA = 'agentsam.result.v1';
 export const SAM_EXPANSION = 'Systematic Autonomous Machinery';
 
-/** @typedef {'local'|'remote'|'sandbox'|'platform'} SamLane */
+/** @typedef {'local'|'remote'|'sandbox'|'platform'|'mcp'} SamLane */
 /** @typedef {'never'|'optional'|'required'} SamModelPolicy */
 /** @typedef {'none'|'optional'|'required'} SamNetworkPolicy */
-/** @typedef {'none'|'local_write'|'remote_read'|'remote_write'|'deploy'|'billable'} SamSideEffects */
+/** @typedef {'none'|'local_write'|'remote_read'|'remote_write'|'deploy'|'billable'|'oauth'} SamSideEffects */
 /** @typedef {'read_only'|'write'|'privileged'} SamRisk */
 /** @typedef {'never'|'optional'|'required'} SamSpendPolicy */
 
+/**
+ * Provider capability / OAuth pack reference (Cloudflare, GitHub, …).
+ * Prefer pack- or capability-scoped consent — never wholesale scope catalogs.
+ * @typedef {object} SamCapabilityRef
+ * @property {string} id
+ * @property {string} [provider]
+ * @property {string[]} [oauth_scopes]
+ * @property {string[]} [feature_packs]
+ */
+
+/**
+ * MCP projection for an operation (server tool surface).
+ * @typedef {object} SamMcpProjection
+ * @property {string} [server_name]
+ * @property {string} [server_url]
+ * @property {string} [tool_name]
+ * @property {string[]} [required_scopes]
+ * @property {string[]} [feature_packs]
+ * @property {'streamable_http'|'sse'|'stdio'} [protocol]
+ */
+
 /**
  * @typedef {object} SamExecutionMeta
  * @property {SamLane[]} lanes
@@ -36,6 +57,8 @@ export const SAM_EXPANSION = 'Systematic Autonomous Machinery';
  * @property {string} [description]
  * @property {SamExecutionMeta} execution
  * @property {{ account?: boolean, provider?: string[] }} [auth]
+ * @property {SamCapabilityRef[]} [capability_refs]
+ * @property {SamMcpProjection} [mcp]
  * @property {SamRisk} risk
  * @property {string} [input_schema]
  * @property {string} [output_schema]
@@ -57,6 +80,7 @@ export const SAM_EXPANSION = 'Systematic Autonomous Machinery';
  * @property {Record<string, unknown>} [execution]
  * @property {string} [cwd]
  * @property {Record<string, string|undefined>} [env]
+ * @property {{ mcp?: SamMcpProjection, capability_refs?: SamCapabilityRef[] }} [projection]
  */
 
 /**
@@ -71,6 +95,7 @@ export const SAM_EXPANSION = 'Systematic Autonomous Machinery';
  * @property {string|null} [input_hash]
  * @property {string|null} [output_hash]
  * @property {'completed'|'failed'|'cancelled'} status
+ * @property {SamMcpProjection} [mcp]
  */
 
 /**

package/src/security/inventory.js

@@ -11,7 +11,7 @@ export function readJson(file) {
   if (!stat.isFile() || stat.size > 32 * 1024 * 1024) throw new Error('Manifest must be a regular JSON file under 32 MiB');
   return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
-export function collectNpmDependencies(projectRoot = process.cwd()) {
+export function collectNpmDependencies(projectRoot = process.cwd(), options = {}) {
   const root = fs.realpathSync(projectRoot);
   const manifest = readJson(path.join(root, 'package.json'));
   const issues = [], dependencies = new Map(), skipped = [];
@@ -20,9 +20,19 @@ export function collectNpmDependencies(projectRoot = process.cwd()) {
   const unsupported = ['pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb'].filter(file => fs.existsSync(path.join(root, file)));
   if (manifest.packageManager && !manifest.packageManager.startsWith('npm@')) issues.push('Selected package manager is not npm; this adapter cannot prove its dependency graph.');
   else if (unsupported.length && !manifest.packageManager) issues.push('Multiple/unsupported package-manager lockfiles; select npm explicitly with packageManager or scan in the owning manager.');
+  const releaseCandidate = options.releaseCandidate || null;
   const add = (name, pkg, location, direct) => {
     if (pkg.link) { skipped.push({ path: location, reason: 'workspace/link (dependencies scanned from lock graph)' }); return; }
-    if (!packageName(name) || !exactVersion(pkg.version) || /^(?:file:|link:|git[+:]|https?:\/\/.*\.git)/i.test(pkg.resolved || '')) {
+    const resolved = String(pkg.resolved || '');
+    const isLocalTarball = /^file:/i.test(resolved);
+    const allowedReleaseCandidate = Boolean(
+      isLocalTarball
+      && releaseCandidate
+      && releaseCandidate.name === name
+      && releaseCandidate.version === pkg.version
+      && releaseCandidate.location === location
+    );
+    if (!packageName(name) || !exactVersion(pkg.version) || (/^(?:file:|link:|git[+:]|https?:\/\/.*\.git)/i.test(resolved) && !allowedReleaseCandidate)) {
       issues.push('Unresolved or non-registry dependency at ' + location);
       return;
     }