arcane-os 0.88.1 → 0.90.0

package/src/local-ai/install.mjs

@@ -5,16 +5,28 @@ import {createRequire} from 'node:module';
 import path from 'node:path';
 import {Readable} from 'node:stream';
 import {pipeline} from 'node:stream/promises';
+import packageMetadata from '../../package.json' with {type:'json'};
 import {ArcaneError,ERROR_CODES,normalizeError,throwIfAborted} from '../errors.mjs';
 import {createEventQueue} from '../event-queue.mjs';
 import {runProcess} from '../process.mjs';
 import {extractLocalAIArchive} from './archive.mjs';
-import {normalizeImageRuntimeRequirement} from './config.mjs';
+import {normalizeImageRuntimeRequirement,normalizeLlamaRuntimeRequirement} from './config.mjs';
 import {normalizeWhisperRuntimeRequirement} from './whisper/config.mjs';
 import {bundledWhisperRuntime, installedWhisperRuntime, installWhisperDistribution, whisperRuntimeSelection} from './whisper/install.mjs';
 
 const is=new Is(false);
 const installations=new Map();
+const onnxWindowsDistribution={
+    version:'1.30.0',
+    revision:'1.30.0-directml-reshape-1',
+    asset:'arcane-onnx-runtime-windows-x64.tar.gz'
+};
+
+function selectedONNXNativeDistribution(runtime,platform,architecture){
+    if(runtime.id!=='onnx'||runtime.url||platform!=='win32'||architecture!=='x64')return null;
+    return (runtime.version??onnxWindowsDistribution.version)===onnxWindowsDistribution.version
+        ?onnxWindowsDistribution:null;
+}
 
 function selectRuntimes(runtimes){
     if(!is.array(runtimes)){
@@ -24,7 +36,8 @@ function selectRuntimes(runtimes){
     for(const item of runtimes){
         const requirement=is.string(item)?{id:item}:item;
         const runtime=requirement?.id==='stable-diffusion.cpp'?normalizeImageRuntimeRequirement(requirement)
-            :requirement?.id==='whisper.cpp'?normalizeWhisperRuntimeRequirement(requirement):requirement;
+            :requirement?.id==='whisper.cpp'?normalizeWhisperRuntimeRequirement(requirement)
+            :requirement?.id==='llama.cpp'?normalizeLlamaRuntimeRequirement(requirement):requirement;
         if(!runtime||!['llama.cpp','ollama','nemo-speech','onnx','stable-diffusion.cpp','whisper.cpp'].includes(runtime.id)){
             throw new ArcaneError(ERROR_CODES.targetUnavailable,`Local AI runtime installation is unavailable for ${String(runtime?.id)}.`);
         }
@@ -32,7 +45,9 @@ function selectRuntimes(runtimes){
         if(prior&&runtime.id==='whisper.cpp'&&whisperRuntimeSelection(prior)!==whisperRuntimeSelection(runtime)){
             throw new ArcaneError(ERROR_CODES.usage,'Select one complete whisper.cpp runtime and model requirement for this operation.');
         }
-        if(prior&&(prior.version!==runtime.version||prior.url!==runtime.url||(runtime.id==='stable-diffusion.cpp'&&prior.backend!==runtime.backend))){
+        if(prior&&(prior.version!==runtime.version||prior.url!==runtime.url
+            ||(['stable-diffusion.cpp','llama.cpp'].includes(runtime.id)&&prior.backend!==runtime.backend)
+            ||(runtime.id==='llama.cpp'&&prior.companionUrl!==runtime.companionUrl))){
             throw new ArcaneError(ERROR_CODES.usage,`Select one ${runtime.id} runtime version and URL for this operation.`);
         }
         if(runtime.version!==undefined&&(!is.string(runtime.version)||!runtime.version)){
@@ -53,7 +68,7 @@ function selectedDirectory(directory){
     return path.resolve(directory);
 }
 
-function releaseAssetNames(id,version,platform,architecture){
+function releaseAssetNames(id,version,platform,architecture,backend){
     if(id==='nemo-speech'){
         if(!['x64','arm64'].includes(architecture))return [];
         const arch=architecture==='x64'?'x86_64':'aarch64';
@@ -71,6 +86,9 @@ function releaseAssetNames(id,version,platform,architecture){
         if(platform==='linux')return [`ollama-linux-${arch}.tar.zst`,`ollama-linux-${arch}.tgz`];
         return [];
     }
+    if(id==='llama.cpp'&&backend==='cuda'){
+        return platform==='win32'&&architecture==='x64'?[`llama-${version}-bin-win-cuda-13.4-x64.zip`]:[];
+    }
     if(!['x64','arm64'].includes(architecture))return [];
     if(platform==='win32')return [`llama-${version}-bin-win-cpu-${architecture}.zip`];
     if(platform==='linux')return [`llama-${version}-bin-ubuntu-${architecture}.tar.gz`,`llama-${version}-bin-ubuntu-${architecture}.zip`];
@@ -93,9 +111,17 @@ async function selectRelease(runtime,platform,architecture,signal){
     if (runtime.id === 'stable-diffusion.cpp') {
         return selectImageRelease(runtime, platform, architecture, signal);
     }
+    const backend=runtime.id==='llama.cpp'?llamaBackendCandidate(runtime,platform,architecture):undefined;
     if(runtime.url){
         const name=path.posix.basename(new URL(runtime.url).pathname);
-        return {version:runtime.version??'custom',url:runtime.url,name};
+        return {
+            version:runtime.version??'custom',url:runtime.url,name,
+            ...(runtime.id==='llama.cpp'?{backend,requestedBackend:runtime.backend}:{}),
+            ...(backend==='cuda'?{companion:{
+                url:runtime.companionUrl,
+                name:path.posix.basename(new URL(runtime.companionUrl).pathname)
+            }}:{})
+        };
     }
     const repository=runtime.id==='nemo-speech'?'NVIDIA/NeMo-Speech.cpp':runtime.id==='llama.cpp'?'ggml-org/llama.cpp':'ollama/ollama';
     const version=runtime.version??(runtime.id==='nemo-speech'?'0.2.0':undefined);
@@ -112,12 +138,38 @@ async function selectRelease(runtime,platform,architecture,signal){
         }
     }
     // Select only published format variants for this exact target distribution.
-    const names=releaseAssetNames(runtime.id,release.tag_name,platform,architecture);
+    const names=releaseAssetNames(runtime.id,release.tag_name,platform,architecture,backend);
     const asset=release.assets?.find(function isSelectedAsset(candidate){return names.includes(candidate.name);});
     if(!asset){
         throw new ArcaneError(ERROR_CODES.targetUnavailable,`${runtime.id} ${release.tag_name} has no published ${platform}/${architecture} runtime archive${names.length?` named ${names.join(' or ')}`:''}.`);
     }
-    return {version:release.tag_name,url:asset.browser_download_url,name:asset.name};
+    let companion;
+    if(backend==='cuda'){
+        const companionName='cudart-llama-bin-win-cuda-13.4-x64.zip';
+        const companionAsset=release.assets?.find(function selectedCudaRuntime(candidate){return candidate.name===companionName;});
+        if(!companionAsset){
+            throw new ArcaneError(ERROR_CODES.targetUnavailable,`llama.cpp ${release.tag_name} has no matching CUDA runtime archive named ${companionName}.`);
+        }
+        companion={url:companionAsset.browser_download_url,name:companionAsset.name};
+    }
+    return {
+        version:release.tag_name,url:asset.browser_download_url,name:asset.name,
+        ...(runtime.id==='llama.cpp'?{backend,requestedBackend:runtime.backend}:{}),
+        ...(companion?{companion}:{})
+    };
+}
+
+function llamaBackendCandidate(runtime,platform,architecture){
+    if(runtime.backend==='cuda'){
+        if(platform!=='win32'||architecture!=='x64'){
+            throw new ArcaneError(ERROR_CODES.targetUnavailable,`The selected llama.cpp CUDA distribution is unavailable for ${platform}/${architecture}.`);
+        }
+        return 'cuda';
+    }
+    // A custom automatic archive declares no backend capability. Official macOS
+    // archives include Metal; requested CPU execution is configured at launch.
+    if(runtime.url)return runtime.backend;
+    return platform==='darwin'?'metal':'cpu';
 }
 
 async function imageBackendCandidate(backend, platform, signal) {
@@ -368,6 +420,7 @@ async function installedRuntime(base,runtime,platform,architecture,signal,reuseW
     const imageBackend = runtime.id === 'stable-diffusion.cpp' && !runtime.url
         ? await imageBackendCandidate(runtime.backend, platform, signal)
         : runtime.backend;
+    const llamaBackend=runtime.id==='llama.cpp'?llamaBackendCandidate(runtime,platform,architecture):null;
     for(const entry of entries){
         throwIfAborted(signal);
         if(!entry.isDirectory())continue;
@@ -380,6 +433,8 @@ async function installedRuntime(base,runtime,platform,architecture,signal,reuseW
         }
         if(installation.requestVersion!==(runtime.version??null)||installation.requestUrl!==(runtime.url??null))continue;
         if (runtime.id === 'stable-diffusion.cpp' && installation.requestBackend !== runtime.backend) continue;
+        if(runtime.id==='llama.cpp'&&((installation.requestBackend??'auto')!==runtime.backend
+            ||(installation.requestCompanionUrl??null)!==(runtime.companionUrl??null)))continue;
         let whisperRequirement;
         if (runtime.id === 'whisper.cpp') {
             if (!installation.requestWhisper) continue;
@@ -388,6 +443,7 @@ async function installedRuntime(base,runtime,platform,architecture,signal,reuseW
         }
         const record=installation.runtime;
         if(record?.id!==runtime.id||record.platform!==platform||record.architecture!==architecture)continue;
+        if(runtime.id==='llama.cpp'&&record.backend!==undefined&&record.backend!==llamaBackend)continue;
         try{
             if(runtime.id==='whisper.cpp'){
                 if(await installedWhisperRuntime(record,signal,!reuseWhisper))return reuseWhisper?{runtime:record,requirement:whisperRequirement}:record;
@@ -423,6 +479,8 @@ async function installedRuntime(base,runtime,platform,architecture,signal,reuseW
             }
             if(runtime.id==='onnx'){
                 if(!is.string(record.root)||!is.string(record.modulePath))continue;
+                const distribution=selectedONNXNativeDistribution(runtime,platform,architecture);
+                if(distribution&&record.nativeDistributionRevision!==distribution.revision)continue;
                 const locations=await onnxRuntimeModule(record.root,platform,architecture,signal);
                 return {...record,...locations,...(runtime.version?{requestedVersion:runtime.version}:{})};
             }
@@ -436,7 +494,11 @@ async function installedRuntime(base,runtime,platform,architecture,signal,reuseW
                 }
                 continue;
             }
-            if((await stat(record.executable)).isFile())return {...record,...(runtime.version?{requestedVersion:runtime.version}:{})};
+            if((await stat(record.executable)).isFile())return {
+                ...record,
+                ...(runtime.id==='llama.cpp'?{backend:record.backend??llamaBackend,requestedBackend:runtime.backend}:{}),
+                ...(runtime.version?{requestedVersion:runtime.version}:{})
+            };
         }catch(error){
             if(runtime.id==='onnx'&&(error.code==='MODULE_NOT_FOUND'||error instanceof SyntaxError))continue;
             if(error.code!=='ENOENT')throw error;
@@ -519,7 +581,7 @@ async function onnxRuntimeModule(root,platform,architecture,signal){
 }
 
 async function installONNXPackage(runtime,{root,directory,platform,architecture,signal,onEvent}){
-    const version=runtime.version??'1.30.0';
+    const version=runtime.version??onnxWindowsDistribution.version;
     await onEvent({type:'local-ai.install.installing',message:`Installing onnxruntime-node ${version} for ${platform}/${architecture}.`,data:{id:runtime.id,version,platform,architecture}});
     await mkdir(root,{recursive:true});
     await writeFile(path.join(root,'package.json'),'{"private":true}\n',{flag:'wx',signal});
@@ -528,14 +590,34 @@ async function installONNXPackage(runtime,{root,directory,platform,architecture,
         '--no-audit','--no-fund','--foreground-scripts','--registry=https://registry.npmjs.org/',
         '--cache',path.join(directory,'npm-cache'),`onnxruntime-node@${runtime.url??version}`
     ],{cwd:root,env:{ONNXRUNTIME_NODE_INSTALL:'skip'},signal,onEvent});
-    return onnxRuntimeModule(root,platform,architecture,signal);
+    const distribution=selectedONNXNativeDistribution(runtime,platform,architecture);
+    if(distribution){
+        const archive=path.join(path.dirname(root),distribution.asset);
+        const nativeDirectory=path.join(root,'node_modules','onnxruntime-node','bin','napi-v6',platform,architecture);
+        const url=`https://github.com/TheWizardNexus/arcane-os-sdk/releases/download/${packageMetadata.version}/${distribution.asset}`;
+        await onEvent({type:'local-ai.install.downloading',message:`Downloading ${distribution.asset}.`,data:{id:runtime.id,asset:distribution.asset,nativeDistributionRevision:distribution.revision}});
+        const response=await upstreamResponse(url,signal);
+        await pipeline(Readable.fromWeb(response.body),createWriteStream(archive,{flags:'wx'}),{signal});
+        await onEvent({type:'local-ai.install.extracting',message:`Preparing ${distribution.asset}.`,data:{id:runtime.id,asset:distribution.asset,nativeDistributionRevision:distribution.revision}});
+        // This is the new attempt's package. Running installations retain their
+        // original trees; the same-version JavaScript and binding stay intact.
+        await extractLocalAIArchive({archive,directory:nativeDirectory,signal,onEvent});
+        await unlink(archive);
+    }
+    const locations=await onnxRuntimeModule(root,platform,architecture,signal);
+    return {...locations,...(distribution?{nativeDistributionRevision:distribution.revision}:{})};
 }
 
 async function installRuntime(runtime,{directory,platform,architecture,signal,onEvent}){
     const runtimeBase=path.join(directory,runtime.id,`${platform}-${architecture}`,encodeURIComponent(runtime.version??'default'));
-    const base=runtime.id==='stable-diffusion.cpp'?path.join(runtimeBase,runtime.backend):runtimeBase;
+    const base=['stable-diffusion.cpp','llama.cpp'].includes(runtime.id)?path.join(runtimeBase,runtime.backend):runtimeBase;
     await onEvent({type:'local-ai.install.starting',message:`Preparing ${runtime.id} for ${platform}/${architecture}.`,data:{id:runtime.id,platform,architecture}});
-    const installed=await installedRuntime(base,runtime,platform,architecture,signal);
+    let installed=await installedRuntime(base,runtime,platform,architecture,signal);
+    // Previous default installations predate backend-specific directories. Keep
+    // those working trees reusable for the same automatic requirement.
+    if(!installed&&runtime.id==='llama.cpp'&&runtime.backend==='auto'){
+        installed=await installedRuntime(runtimeBase,runtime,platform,architecture,signal);
+    }
     if(installed){
         await onEvent({type:'local-ai.install.available',message:`${runtime.id} ${installed.version} is already installed.`,data:installed});
         return installed;
@@ -550,6 +632,7 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
     const attempt=await mkdtemp(path.join(base,'install-'));
     const root=path.join(attempt,'runtime');
     const archive=release&&runtime.id!=='stable-diffusion.cpp'?path.join(attempt,release.name):null;
+    const companionArchive=release?.companion?path.join(attempt,'companion',release.companion.name):null;
     let completed=false;
     try{
         let locations;
@@ -563,19 +646,46 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
                 {root, directory, platform, architecture, signal, onEvent}
             );
         }else{
-            await onEvent({type:'local-ai.install.downloading',message:`Downloading ${runtime.id} ${release.version}.`,data:{id:runtime.id,version:release.version,platform,architecture}});
-            const response=await upstreamResponse(release.url,signal);
-            await pipeline(Readable.fromWeb(response.body),createWriteStream(archive,{flags:'wx'}),{signal});
-            await onEvent({type:'local-ai.install.extracting',message:`Extracting ${runtime.id} ${release.version}.`,data:{id:runtime.id,version:release.version}});
-            await extractLocalAIArchive({archive,directory:root,signal,onEvent});
-            locations={version:release.version,...(runtime.id==='nemo-speech'
+            const assets=[{url:release.url,name:release.name,archive}];
+            if(companionArchive){
+                await mkdir(path.dirname(companionArchive));
+                assets.push({...release.companion,archive:companionArchive});
+            }
+            const downloads=await Promise.allSettled(assets.map(async function downloadRuntimeArchive(asset){
+                await onEvent({
+                    type:'local-ai.install.downloading',
+                    message:runtime.id==='llama.cpp'?`Downloading ${runtime.id} ${release.version}: ${asset.name}.`:`Downloading ${runtime.id} ${release.version}.`,
+                    data:{id:runtime.id,version:release.version,platform,architecture,...(runtime.id==='llama.cpp'?{asset:asset.name}:{})}
+                });
+                const response=await upstreamResponse(asset.url,signal);
+                await pipeline(Readable.fromWeb(response.body),createWriteStream(asset.archive,{flags:'wx'}),{signal});
+            }));
+            const failures=downloads.filter(function archiveDownloadFailed(outcome){return outcome.status==='rejected';});
+            if(failures.length===1)throw failures[0].reason;
+            if(failures.length>1){
+                throw new AggregateError(failures.map(function archiveDownloadFailure(outcome){return outcome.reason;}),`Download of ${runtime.id} archives failed.`);
+            }
+            // The pair downloads independently, then extracts in order because
+            // both archives populate the same new runtime directory.
+            for(const asset of assets){
+                await onEvent({
+                    type:'local-ai.install.extracting',
+                    message:runtime.id==='llama.cpp'?`Extracting ${runtime.id} ${release.version}: ${asset.name}.`:`Extracting ${runtime.id} ${release.version}.`,
+                    data:{id:runtime.id,version:release.version,...(runtime.id==='llama.cpp'?{asset:asset.name}:{})}
+                });
+                await extractLocalAIArchive({archive:asset.archive,directory:root,signal,onEvent});
+            }
+            locations={version:release.version,
+                ...(runtime.id==='llama.cpp'?{backend:release.backend,requestedBackend:release.requestedBackend}:{}),
+                ...(runtime.id==='nemo-speech'
                 ?await nemoRuntimeDirectories(root,signal)
                 :{executable:await runtimeExecutable(root,runtime.id,platform,signal)})};
         }
         const record={id:runtime.id,platform,architecture,root,...locations,...(runtime.version?{requestedVersion:runtime.version}:{})};
         throwIfAborted(signal);
         if(archive)await unlink(archive);
-        await writeFile(path.join(attempt,'installation.json'),`${JSON.stringify({requestVersion:runtime.version??null,requestUrl:runtime.url??null,...(runtime.id==='stable-diffusion.cpp'?{requestBackend:runtime.backend}:{}),...(runtime.id==='whisper.cpp'?{requestWhisper:whisperRuntimeSelection(runtime)}:{}),runtime:record},null,2)}\n`,{flag:'wx',signal});
+        if(companionArchive)await unlink(companionArchive);
+        await writeFile(path.join(attempt,'installation.json'),`${JSON.stringify({requestVersion:runtime.version??null,requestUrl:runtime.url??null,...(['stable-diffusion.cpp','llama.cpp'].includes(runtime.id)?{requestBackend:runtime.backend}:{}),...(runtime.id==='llama.cpp'?{requestCompanionUrl:runtime.companionUrl??null}:{}),...(runtime.id==='whisper.cpp'?{requestWhisper:whisperRuntimeSelection(runtime)}:{}),runtime:record},null,2)}\n`,{flag:'wx',signal});
         completed=true;
         await onEvent({type:'local-ai.install.completed',message:`${runtime.id} ${record.version} is available.`,data:record});
         return record;
@@ -595,7 +705,7 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
 
 function shareInstallation(runtime,options){
     throwIfAborted(options.signal);
-    const key=JSON.stringify([options.directory,options.platform,options.architecture,runtime.id,runtime.version??null,runtime.url??null,runtime.id==='stable-diffusion.cpp'?runtime.backend:null,runtime.id==='whisper.cpp'?whisperRuntimeSelection(runtime):null]);
+    const key=JSON.stringify([options.directory,options.platform,options.architecture,runtime.id,runtime.version??null,runtime.url??null,['stable-diffusion.cpp','llama.cpp'].includes(runtime.id)?runtime.backend:null,runtime.id==='whisper.cpp'?whisperRuntimeSelection(runtime):null,runtime.id==='llama.cpp'?runtime.companionUrl??null:null]);
     let entry=installations.get(key);
     if(entry?.controller.signal.aborted){
         // The prior cancelled attempt owns its cleanup. A later request waits

package/src/local-ai/llama-execution-windows.ps1

@@ -0,0 +1,158 @@
+# Invoked through stdin by the SDK's owned process; stdout contains one JSON record.
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+
+try {
+    # Enumerate the installed driver's devices in this helper only. An empty
+    # CUDA_VISIBLE_DEVICES value hides every device, so remove the inherited value.
+    [Environment]::SetEnvironmentVariable('CUDA_VISIBLE_DEVICES', $null, [EnvironmentVariableTarget]::Process)
+
+    Add-Type -TypeDefinition @'
+using System;
+using System.Globalization;
+using System.Runtime.InteropServices;
+using System.Text;
+
+namespace Arcane.LocalAI {
+    [StructLayout(LayoutKind.Sequential)]
+    public struct AdapterLuid {
+        public uint LowPart;
+        public int HighPart;
+    }
+
+    public sealed class CudaDeviceIdentity {
+        public string Uuid;
+        public uint NodeMask;
+        public AdapterLuid Luid;
+        public string UuidFunction;
+
+        // NVIDIA CU_DEVICE_ATTRIBUTE_TCC_DRIVER is 35. CUDA's Windows LUID
+        // contract is undefined in TCC mode, so only WDDM devices can be matched.
+        // https://nvidia.github.io/cuda-python/cuda-bindings/latest/module/driver.html
+        private const int TccDriverAttribute = 35;
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuInit(uint flags);
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuDeviceGetCount(out int count);
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuDeviceGet(out int device, int ordinal);
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuDeviceGetAttribute(out int value, int attribute, int device);
+
+        // CUDA writes the native Windows LUID layout: unsigned LowPart followed
+        // by signed HighPart. Marshaling the struct preserves that native layout.
+        // https://learn.microsoft.com/en-us/windows/win32/api/winnt/ns-winnt-luid
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuDeviceGetLuid(out AdapterLuid luid, out uint nodeMask, int device);
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuDeviceGetUuid_v2([Out] byte[] uuid, int device);
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuDeviceGetUuid([Out] byte[] uuid, int device);
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuGetErrorName(int error, out IntPtr name);
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuGetErrorString(int error, out IntPtr message);
+
+        private static void Check(int result, string operation) {
+            if (result == 0) return;
+            IntPtr name;
+            IntPtr message;
+            int nameResult = cuGetErrorName(result, out name);
+            int messageResult = cuGetErrorString(result, out message);
+            throw new InvalidOperationException(
+                operation + " returned CUDA error " + result + ": " +
+                (nameResult == 0 ? Marshal.PtrToStringAnsi(name) : "cuGetErrorName returned " + nameResult) + "; " +
+                (messageResult == 0 ? Marshal.PtrToStringAnsi(message) : "cuGetErrorString returned " + messageResult)
+            );
+        }
+
+        private static string ReadUuid(int device, out string function) {
+            // CUuuid's 16 native octets are unavoidable ABI storage. CUDA UUID
+            // text keeps their order; System.Guid would reverse several fields.
+            byte[] uuid = new byte[16];
+            int result;
+            try {
+                result = cuDeviceGetUuid_v2(uuid, device);
+                function = "cuDeviceGetUuid_v2";
+            } catch (EntryPointNotFoundException) {
+                // Older drivers expose the original function for this same
+                // device. No device or backend selection changes on this path.
+                result = cuDeviceGetUuid(uuid, device);
+                function = "cuDeviceGetUuid";
+            }
+            Check(result, function);
+            StringBuilder text = new StringBuilder("GPU-");
+            for (int index = 0; index < uuid.Length; index++) {
+                if (index == 4 || index == 6 || index == 8 || index == 10) text.Append('-');
+                text.Append(uuid[index].ToString("x2", CultureInfo.InvariantCulture));
+            }
+            return text.ToString();
+        }
+
+        public static CudaDeviceIdentity Resolve(uint lowPart, int highPart) {
+            Check(cuInit(0), "cuInit");
+            int count;
+            Check(cuDeviceGetCount(out count), "cuDeviceGetCount");
+            CudaDeviceIdentity matched = null;
+            int tccCount = 0;
+            for (int ordinal = 0; ordinal < count; ordinal++) {
+                int device;
+                Check(cuDeviceGet(out device, ordinal), "cuDeviceGet(" + ordinal + ")");
+                int tcc;
+                Check(cuDeviceGetAttribute(out tcc, TccDriverAttribute, device), "cuDeviceGetAttribute(TCC_DRIVER, " + ordinal + ")");
+                if (tcc != 0) {
+                    tccCount++;
+                    continue;
+                }
+                AdapterLuid luid;
+                uint nodeMask;
+                Check(cuDeviceGetLuid(out luid, out nodeMask, device), "cuDeviceGetLuid(" + ordinal + ")");
+                if (luid.LowPart != lowPart || luid.HighPart != highPart) continue;
+                if (matched != null) {
+                    throw new InvalidOperationException("Multiple CUDA devices share the selected adapter LUID; the catalog selection cannot identify one CUDA device.");
+                }
+                string function;
+                string uuid = ReadUuid(device, out function);
+                matched = new CudaDeviceIdentity { Uuid = uuid, NodeMask = nodeMask, Luid = luid, UuidFunction = function };
+            }
+            if (matched == null) {
+                throw new InvalidOperationException(
+                    "No WDDM CUDA device matches the selected adapter LUID. CUDA devices enumerated: " + count +
+                    "; TCC devices without a defined LUID: " + tccCount + "."
+                );
+            }
+            return matched;
+        }
+    }
+}
+'@
+
+    $lowPart = [uint32]::Parse($env:ARCANE_LLAMA_LUID_LOW, [Globalization.CultureInfo]::InvariantCulture)
+    $highPart = [int32]::Parse($env:ARCANE_LLAMA_LUID_HIGH, [Globalization.CultureInfo]::InvariantCulture)
+    $device = [Arcane.LocalAI.CudaDeviceIdentity]::Resolve($lowPart, $highPart)
+    [ordered]@{
+        uuid = $device.Uuid
+        nodeMask = $device.NodeMask
+        adapterLuid = [ordered]@{
+            lowPart = $device.Luid.LowPart
+            highPart = $device.Luid.HighPart
+        }
+        driverMode = 'wddm'
+        uuidFunction = $device.UuidFunction
+    } | ConvertTo-Json -Depth 4 -Compress
+} catch {
+    [Console]::Error.WriteLine($_.Exception.ToString())
+    if ($null -ne $_.ErrorDetails) { [Console]::Error.WriteLine($_.ErrorDetails.Message) }
+    if ($null -ne $_.InvocationInfo) { [Console]::Error.WriteLine($_.InvocationInfo.PositionMessage) }
+    if ($_.ScriptStackTrace) { [Console]::Error.WriteLine($_.ScriptStackTrace) }
+    exit 1
+}

package/src/local-ai/llama-execution.mjs

@@ -0,0 +1,169 @@
+import {readFile} from 'node:fs/promises';
+import path from 'node:path';
+import Is from 'strong-type';
+import {ArcaneError, ERROR_CODES, throwIfAborted} from '../errors.mjs';
+import {runProcess} from '../process.mjs';
+
+const is = new Is(false);
+
+/**
+ * Resolve one explicit catalog selection for a new native llama server lifetime.
+ * Default selection performs no discovery. Hardware identity and launch options
+ * are configuration evidence; the server's observed execution target stays null.
+ */
+export async function resolveLlamaExecution({
+    executionTarget, executionDevices, runtime, signal, onEvent
+} = {}) {
+    throwIfAborted(signal);
+    if (executionTarget === undefined || executionTarget === null) {
+        const cpu = runtime?.requestedBackend === 'cpu';
+        return {
+            args: cpu ? ['--device', 'none', '--gpu-layers', '0'] : [],
+            env: {},
+            execution: {
+                requestedTarget: null,
+                resolvedDevice: null,
+                resolution: 'automatic',
+                reason: cpu ? 'runtime-backend-selected' : 'engine-default-required',
+                configuredTarget: cpu ? {backend: 'cpu', device: 'none', gpuLayers: 0} : null,
+                observedTarget: null,
+                fallback: false
+            }
+        };
+    }
+    if (!is.function(executionDevices?.resolveTarget)) {
+        throw new ArcaneError(
+            'LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED',
+            'Explicit llama.cpp device selection requires the host execution-device catalog.',
+            {details: {requestedTarget: executionTarget}}
+        );
+    }
+    // The persistent device ID is resolved again for this load because a Windows
+    // adapter LUID belongs to the current host session, not the saved selection.
+    const resolution = await executionDevices.resolveTarget(
+        {executionTarget, refresh: true, signal}
+    );
+    throwIfAborted(signal);
+    const execution = {
+        ...resolution,
+        configuredTarget: null,
+        observedTarget: null,
+        fallback: false
+    };
+    if (resolution.resolution !== 'matched' || !resolution.resolvedDevice) {
+        throw new ArcaneError(
+            resolution.resolution === 'unsupported'
+                ? 'LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED'
+                : 'LOCAL_AI_EXECUTION_TARGET_UNAVAILABLE',
+            `The selected llama.cpp execution device could not be resolved: ${resolution.reason}.`,
+            {details: execution}
+        );
+    }
+    const device = resolution.resolvedDevice;
+    if (device.kind === 'cpu') {
+        execution.configuredTarget = {
+            backend: 'cpu', deviceId: device.deviceId, device: 'none', gpuLayers: 0
+        };
+        return {args: ['--device', 'none', '--gpu-layers', '0'], env: {}, execution};
+    }
+    if (device.kind !== 'gpu' || process.platform !== 'win32') {
+        throw new ArcaneError(
+            'LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED',
+            `Exact llama.cpp ${device.kind} selection is unavailable on ${process.platform}.`,
+            {details: execution}
+        );
+    }
+    if (runtime?.requestedBackend === 'cpu') {
+        throw new ArcaneError(
+            'LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED',
+            'The selected GPU is incompatible with the explicit llama.cpp CPU runtime configuration.',
+            {details: execution}
+        );
+    }
+    if (runtime?.backend !== 'cuda') {
+        throw new ArcaneError(
+            'LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED',
+            'Exact Windows GPU selection requires a llama.cpp CUDA runtime.',
+            {details: {...execution, runtimeBackend: runtime?.backend ?? null}}
+        );
+    }
+    const adapterLuid = device.addresses?.adapterLuid;
+    if (!is.integer(adapterLuid?.lowPart) || adapterLuid.lowPart < 0 || adapterLuid.lowPart > 0xffffffff
+        || !is.integer(adapterLuid?.highPart) || adapterLuid.highPart < -0x80000000 || adapterLuid.highPart > 0x7fffffff) {
+        throw new ArcaneError(
+            'LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED',
+            'The selected Windows GPU has no current adapter LUID for CUDA identity resolution.',
+            {details: execution}
+        );
+    }
+    const identity = await resolveWindowsCudaIdentity({adapterLuid, signal, onEvent});
+    throwIfAborted(signal);
+    execution.configuredTarget = {
+        backend: 'cuda',
+        deviceId: device.deviceId,
+        device: 'CUDA0',
+        uuid: identity.uuid,
+        nodeMask: identity.nodeMask,
+        adapterLuid: identity.adapterLuid,
+        driverMode: identity.driverMode,
+        identitySource: 'nvidia-cuda-driver',
+        uuidFunction: identity.uuidFunction,
+        splitMode: 'none',
+        mainGpu: 0,
+        gpuLayers: 'all'
+    };
+    if (identity.diagnostics !== '') {
+        execution.diagnostics = [{source: 'cuda-driver', message: identity.diagnostics}];
+    }
+    // A single full UUID makes CUDA0 identify the selected physical GPU in the
+    // fresh server process, independent of DXGI or inherited CUDA ordinal order.
+    return {
+        args: ['--device', 'CUDA0', '--split-mode', 'none', '--main-gpu', '0', '--gpu-layers', 'all'],
+        env: {CUDA_VISIBLE_DEVICES: identity.uuid},
+        execution
+    };
+}
+
+async function resolveWindowsCudaIdentity({adapterLuid, signal, onEvent}) {
+    const script = await readFile(
+        new URL('./llama-execution-windows.ps1', import.meta.url),
+        {encoding: 'utf8', signal}
+    );
+    throwIfAborted(signal);
+    const command = process.env.SystemRoot
+        ? path.join(process.env.SystemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+        : 'powershell.exe';
+    async function* identityInput() {
+        yield `& {\n${script}\n}\n\n`;
+    }
+    const result = await runProcess(
+        command,
+        ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '-'],
+        {
+            signal,
+            onEvent,
+            env: {
+                ARCANE_LLAMA_LUID_LOW: String(adapterLuid.lowPart),
+                ARCANE_LLAMA_LUID_HIGH: String(adapterLuid.highPart)
+            },
+            input: identityInput(),
+            captureOutput: true,
+            emitOutputEvents: false
+        }
+    );
+    throwIfAborted(signal);
+    let identity;
+    try {
+        identity = JSON.parse(result.stdout);
+        if (!is.string(identity?.uuid) || identity.uuid === '' || !is.integer(identity.nodeMask)) {
+            throw new TypeError('The CUDA driver identity helper returned no device identity.');
+        }
+    } catch (error) {
+        throw new ArcaneError(
+            ERROR_CODES.operationFailed,
+            'Could not read the selected CUDA device identity.',
+            {cause: error, details: result}
+        );
+    }
+    return {...identity, diagnostics: result.stderr};
+}