arcane-os 0.88.1 → 0.89.0

package/src/core/services/local-ai.mjs

@@ -130,6 +130,7 @@ export function createLocalAIService(configuration, {appRoot, runtimes = [], sig
     const owner = {};
     const events = createArcaneEventSource(owner, {source: 'core-local-ai', eventTypes: ['localai.state']});
     let context;
+    let modelAssetOwner;
     let closed = false;
     let onnx;
     let onnxRecovery;
@@ -334,17 +335,31 @@ export function createLocalAIService(configuration, {appRoot, runtimes = [], sig
 
     function restartEngine(engine) {
         if (engine.recovering) return engine.recovering;
+        const selecting = engine.selecting;
         const recovering = Promise.resolve().then(async function recoverSelectedEngine() {
             lifetimeSignal.throwIfAborted();
+            if (selecting) await selecting;
+            const previous = engine.launch ?? engine.selection;
+            // Keep a second use across replacement, before the old process
+            // releases its own use on exit.
+            const projection = previous?.assetProjectionId
+                ? modelAssetOwner.retain(previous.assetProjectionId) : undefined;
+            const replacement = previous ? {...previous, projection} : undefined;
             engine.controller.abort();
-            await engine.server.close();
-            await Promise.allSettled([...engine.loads.values()]);
-            lifetimeSignal.throwIfAborted();
-            engine.models = [];
-            engine.modelChanges.clear();
-            engine.revision = 0;
-            engine.released = false;
-            startEngine(engine);
+            try {
+                await engine.server.close();
+                await Promise.allSettled([...engine.loads.values()]);
+                lifetimeSignal.throwIfAborted();
+                engine.models = [];
+                engine.modelChanges.clear();
+                engine.revision = 0;
+                engine.released = false;
+                startEngine(engine, replacement);
+            } catch (error) {
+                try { await projection?.release(); }
+                catch (cleanupError) { throw new AggregateError([error, cleanupError], 'llama.cpp recovery and model release failed.', {cause: error}); }
+                throw error;
+            }
         });
         engine.recovering = recovering;
         function releaseRecovery() {
@@ -360,6 +375,7 @@ export function createLocalAIService(configuration, {appRoot, runtimes = [], sig
         if (!engine) throw failure('LOCAL_AI_RUNTIME_NOT_SELECTED', `${id} is not selected in this application's localAI configuration.`);
         if (engine.recovering) await awaitReadiness(engine.recovering, signal);
         if (engine.stopping) await awaitReadiness(engine.stopping, signal);
+        if (engine.selecting) await awaitReadiness(engine.selecting, signal);
         // An external server exposes no readiness subscription during initial
         // loading. A new explicit load makes one fresh attempt, without polling.
         if (retryLoading && engine.state.state === 'loading') {
@@ -431,7 +447,115 @@ export function createLocalAIService(configuration, {appRoot, runtimes = [], sig
         return {...engine.state, models: [...engine.models]};
     }
 
-    async function loadLlama({model}, request) {
+    async function activateLlamaSelection(engine, parameters, request) {
+        const {model, assetProjectionId, resourcePaths} = parameters;
+        const signal = AbortSignal.any([lifetimeSignal, request.signal]);
+        signal.throwIfAborted();
+        const previous = engine.launch ?? engine.selection;
+        const retained = previous?.model === model ? previous : undefined;
+        const projectionId = assetProjectionId ?? retained?.assetProjectionId;
+        const memberPath = resourcePaths?.model ?? (projectionId === retained?.assetProjectionId ? retained?.memberPath : undefined);
+        const executionTarget = parameters.executionTarget !== undefined
+            ? parameters.executionTarget : retained ? retained.executionTarget : config.llamaCpp?.executionTarget;
+        if (executionTarget !== undefined && executionTarget !== null
+            && (!is.string(executionTarget.deviceId) || !executionTarget.deviceId)) {
+            throw new TypeError('A llama.cpp execution target needs its host deviceId, or null for the configured default.');
+        }
+        if (projectionId !== undefined && (!is.string(memberPath) || !memberPath)) {
+            throw failure('LOCAL_AI_MODEL_RESOURCE_REQUIRED', 'Projected llama.cpp loading needs resourcePaths.model.');
+        }
+        if (resourcePaths !== undefined && projectionId === undefined) {
+            throw failure('LOCAL_AI_MODEL_PROJECTION_REQUIRED', 'resourcePaths needs its retained assetProjectionId.');
+        }
+        if (retained && retained.assetProjectionId === projectionId && retained.memberPath === memberPath
+            && (retained.executionTarget?.deviceId ?? null) === (executionTarget?.deviceId ?? null)
+            && engine.state.available) {
+            return prepareLlamaModel(engine, model, signal);
+        }
+        if (!await awaitReadiness(engine.server.management, signal)) {
+            if (engine.server.external) {
+                throw failure('LOCAL_AI_EXTERNAL_SELECTION_UNSUPPORTED', 'The existing llama.cpp server owns its model and device selection. Use an available listener for SDK-managed model loading.');
+            }
+            await engine.ready;
+            throw failure('LOCAL_AI_RUNTIME_UNAVAILABLE', 'No managed llama.cpp executable is available.');
+        }
+        let projection;
+        let launch;
+        function cancelSelectedLoad() {
+            if (engine.launch === launch) engine.controller.abort(signal.reason);
+        }
+        try {
+            const configuration = {...config.llamaCpp, executionTarget};
+            if (projectionId !== undefined) {
+                const assets = modelAssetOwner ?? await context.getService('model-assets');
+                if (!assets) throw failure('LOCAL_AI_MODEL_ASSETS_UNAVAILABLE', 'The Core model-assets service is unavailable.');
+                signal.throwIfAborted();
+                modelAssetOwner = assets;
+                projection = assets.retain(projectionId);
+                const member = projection.members.find(function selectedMember(value) { return value.path === memberPath; });
+                if (!member) throw failure('LOCAL_AI_MODEL_RESOURCE_UNAVAILABLE', `The projection does not contain ${memberPath}.`);
+                configuration.model = member.nativePath;
+                configuration.alias = model;
+            }
+            launch = {model, assetProjectionId: projectionId, memberPath, executionTarget, configuration, projection};
+            // One server owns this listener. Only its replacement is serialized;
+            // ordinary router model loads keep their independent existing flow.
+            signal.throwIfAborted();
+            engine.controller.abort();
+            await engine.server.close();
+            await Promise.allSettled([...engine.loads.values()]);
+            signal.throwIfAborted();
+            engine.models = [];
+            engine.modelChanges.clear();
+            engine.revision = 0;
+            engine.released = false;
+            startEngine(engine, launch);
+            signal.addEventListener('abort', cancelSelectedLoad, {once: true});
+            if (signal.aborted) cancelSelectedLoad();
+            await engine.ready;
+            signal.throwIfAborted();
+            const result = await prepareLlamaModel(engine, model, signal);
+            signal.throwIfAborted();
+            return result;
+        } catch (error) {
+            try {
+                if (launch && engine.launch === launch) {
+                    engine.controller.abort(error);
+                    await engine.server.close();
+                }
+                await projection?.release();
+            } catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], 'llama.cpp loading and model release failed.', {cause: error});
+            }
+            throw error;
+        } finally {
+            signal.removeEventListener('abort', cancelSelectedLoad);
+        }
+    }
+
+    function selectLlamaModel(parameters, request) {
+        const engine = engines.get('llama.cpp');
+        if (!engine) throw failure('LOCAL_AI_RUNTIME_NOT_SELECTED', "llama.cpp is not selected in this application's localAI configuration.");
+        const preceding = engine.selecting;
+        const recovering = engine.recovering;
+        const stopping = engine.stopping;
+        const task = (async function replaceSelectedLlamaModel() {
+            if (preceding) await Promise.allSettled([preceding]);
+            if (recovering) await recovering;
+            if (stopping) await stopping;
+            return activateLlamaSelection(engine, parameters, request);
+        })();
+        engine.selecting = task;
+        function releaseSelection() { if (engine.selecting === task) engine.selecting = null; }
+        task.then(releaseSelection, releaseSelection);
+        return task;
+    }
+
+    async function loadLlama(parameters, request) {
+        const {model} = parameters;
+        if (parameters.assetProjectionId !== undefined || parameters.resourcePaths !== undefined || parameters.executionTarget !== undefined) {
+            return selectLlamaModel(parameters, request);
+        }
         const engine = await engineReady('llama.cpp', request.signal, {retryLoading: true});
         let task = engine.loads.get(model);
         if (!task) {
@@ -451,6 +575,17 @@ export function createLocalAIService(configuration, {appRoot, runtimes = [], sig
         return awaitReadiness(task, request.signal);
     }
 
+    async function releaseLlamaServer(engine) {
+        engine.controller.abort();
+        engine.stopping = engine.server.close();
+        await engine.stopping;
+        engine.stopping = null;
+        engine.released = true;
+        engine.models = engine.models.map(function unloadedModel(value) { return {...value, loaded: false}; });
+        publish();
+        return {...engine.state, models: [...engine.models], released: true, unloaded: true};
+    }
+
     async function chatLlama({model, payload, stream = false, streamId}, request) {
         model = payload?.model ?? model;
         const engine = await engineReady('llama.cpp', request.signal, {retryLoading: true});
@@ -556,17 +691,38 @@ export function createLocalAIService(configuration, {appRoot, runtimes = [], sig
         return result;
     }
 
-    function startEngine(engine) {
+    function startEngine(engine, launch) {
+        if (!launch && engine.selection) {
+            // A stopped selected projection may have been released by its
+            // preparation owner. Retaining it either succeeds or reports that
+            // it must be prepared again; never start a different default model.
+            const projection = engine.selection.assetProjectionId
+                ? modelAssetOwner.retain(engine.selection.assetProjectionId) : undefined;
+            launch = {...engine.selection, projection};
+        }
+        if (launch) {
+            const {projection, ...selection} = launch;
+            engine.selection = selection;
+        }
         engine.controller = new AbortController();
         engine.signal = AbortSignal.any([lifetimeSignal, engine.controller.signal]);
         engine.ollamaRevision = 0;
         engine.ollamaAppliedRevision = 0;
         const signal = engine.signal;
+        engine.launch = launch;
         engine.server = createLocalAIServer({
             id: engine.id, appRoot, runtime: runtimes.find(function runtimeRecord(record) { return record.id === engine.id; }),
-            configuration: engine.id === 'llama.cpp' ? config.llamaCpp : config.ollama,
-            signal, onEvent,
-            onState(state) { engine.state = {...engine.state, ...state, error: state.error ?? null}; publish(); }
+            configuration: engine.id === 'llama.cpp' ? launch?.configuration ?? config.llamaCpp : config.ollama,
+            signal, onEvent, executionDevices, requireManaged: Boolean(launch),
+            onState(state) { engine.state = {...engine.state, ...state, error: state.error ?? null}; publish(); },
+            async onExit() {
+                await launch?.projection?.release();
+                if (launch && engine.launch === launch) {
+                    engine.launch = undefined;
+                    engine.models = engine.models.map(function releasedModel(model) { return {...model, loaded: false}; });
+                    if (!closed) publish();
+                }
+            }
         });
         engine.ready = engine.server.ready.then(async function prepareModelCatalog() {
             await refreshModels(engine, signal);
@@ -671,20 +827,25 @@ export function createLocalAIService(configuration, {appRoot, runtimes = [], sig
             },
             'llama.load': loadLlama,
             'llama.unload': async function unloadLlama({model}, request) {
+                const selected = engines.get('llama.cpp');
+                if (selected?.launch?.model === model && selected.selecting) {
+                    selected.controller.abort(failure('LOCAL_AI_MODEL_UNLOADED', `The application unloaded ${model}.`));
+                }
+                if (selected?.selecting) await Promise.allSettled([selected.selecting]);
+                request.signal.throwIfAborted();
+                // A failed or cancelled projected startup may already have
+                // stopped. Release joins its cleanup rather than replaying the
+                // rejected readiness promise as a new unload failure.
+                if (selected?.selection?.model === model && !selected.state.available && !selected.server.external) {
+                    return releaseLlamaServer(selected);
+                }
                 const engine = await engineReady('llama.cpp', request.signal, {resumeReleased: false});
                 if (engine.released) return {...engine.state, models: [...engine.models], released: true, unloaded: true};
                 engine.loadControllers.get(model)?.abort(failure('LOCAL_AI_MODEL_UNLOADED', `The application unloaded ${model}.`));
                 if (engine.loads.has(model)) await Promise.allSettled([engine.loads.get(model)]);
                 if (!engine.router) {
                     if (!engine.server.owned) return {...engine.state, models: [...engine.models], released: true, unloaded: false};
-                    engine.controller.abort();
-                    engine.stopping = engine.server.close();
-                    await engine.stopping;
-                    engine.stopping = null;
-                    engine.released = true;
-                    engine.models = engine.models.map(function unloadedModel(value) { return {...value, loaded: false}; });
-                    publish();
-                    return {...engine.state, models: [...engine.models], released: true, unloaded: true};
+                    return releaseLlamaServer(engine);
                 }
                 await requestLocalJSON({url: engine.server.url, path: '/models/unload', method: 'POST', payload: {model}, signal: request.signal});
                 return refreshModels(engine, request.signal);
@@ -712,7 +873,7 @@ export function createLocalAIService(configuration, {appRoot, runtimes = [], sig
             ]);
             stopONNXSubscription?.();
             await Promise.allSettled([...jobs, ...(onnxRecovery ? [onnxRecovery] : []), ...[...engines.values()].flatMap(function pendingWork(engine) {
-                return [...engine.loads.values(), ...(engine.recovering ? [engine.recovering] : [])];
+                return [...engine.loads.values(), ...(engine.recovering ? [engine.recovering] : []), ...(engine.selecting ? [engine.selecting] : [])];
             })]);
             events.dispose();
             const failures = results.filter(function failed(result) { return result.status === 'rejected'; }).map(function cause(result) { return result.reason; });

package/src/installed-sdk-runtime.mjs

@@ -74,6 +74,7 @@ async function writeWorkspaceLock(lockPath,lock){
 export async function materializeInstalledSdkRuntime({
     workspaceRoot,
     sdkPackageSource,
+    browserDecisions=false,
     workspaceOperationLease,
     signal,
     onEvent
@@ -93,6 +94,7 @@ export async function materializeInstalledSdkRuntime({
             runtimeRoot:authority.installation.runtimeRoot,
             browserRuntimeRoot:authority.installation.browserRuntimeRoot,
             sdkVersion:authority.installation.packageVersion,
+            browserDecisions,
             signal,
             onEvent
         });

package/src/local-ai/config.mjs

@@ -10,6 +10,21 @@ import {normalizeWhisperRuntimeRequirement} from './whisper/config.mjs';
 const is = new Is(false);
 export const LOCAL_AI_RUNTIME_IDS = ['llama.cpp', 'ollama', 'onnx', 'stable-diffusion.cpp', 'whisper.cpp'];
 
+/** Select a llama distribution without discovering hardware or acquiring it. */
+export function normalizeLlamaRuntimeRequirement(record) {
+    const backend = record.backend ?? 'auto';
+    if (!['auto', 'cpu', 'cuda'].includes(backend)) {
+        throw new ArcaneError(ERROR_CODES.usage, `Unknown llama.cpp backend: ${String(backend)}.`);
+    }
+    if (record.companionUrl !== undefined && (!is.string(record.companionUrl) || !record.companionUrl)) {
+        throw new ArcaneError(ERROR_CODES.usage, 'llama.cpp companionUrl must be a nonempty string.');
+    }
+    if (record.url && backend === 'cuda' && !record.companionUrl) {
+        throw new ArcaneError(ERROR_CODES.usage, 'A custom llama.cpp CUDA archive requires an explicit companionUrl for its CUDA runtime libraries.');
+    }
+    return {...record, backend};
+}
+
 /** Image requirements describe assets without acquiring or loading a model. */
 export function normalizeImageRuntimeRequirement(record) {
     const backend = record.backend ?? 'auto';
@@ -61,6 +76,7 @@ export function normalizeLocalAIConfig(value) {
         if (!record || !LOCAL_AI_RUNTIME_IDS.includes(record.id)) {
             throw new ArcaneError(ERROR_CODES.usage, `Unknown local AI runtime: ${String(record?.id ?? item)}.`);
         }
+        if (record.id === 'llama.cpp') return normalizeLlamaRuntimeRequirement(record);
         if (record.id === 'stable-diffusion.cpp') return normalizeImageRuntimeRequirement(record);
         if (record.id === 'whisper.cpp') return normalizeWhisperRuntimeRequirement(record);
         return {...record};

package/src/local-ai/dev.mjs

@@ -47,8 +47,8 @@ export function createDevelopmentLocalAI({
     const imageSelected = selected.runtimes.some(function selectedImageRuntime(requirement) {
         return requirement.id === 'stable-diffusion.cpp';
     });
-    if (imageSelected || selected.runtimes.some(function selectedONNXRuntime(requirement) {
-        return requirement.id === 'onnx';
+    if (imageSelected || selected.runtimes.some(function selectedProjectedRuntime(requirement) {
+        return ['onnx', 'llama.cpp'].includes(requirement.id);
     })) {
         modelAssets = createModelAssetService({appRoot});
         definitions.push(modelAssets);

package/src/local-ai/discover.mjs

@@ -27,6 +27,9 @@ export async function discoverLocalAIRuntimes({config,appRoot,signal}={}){
     const outcomes=await Promise.allSettled(selected.map(async function discoverRuntime(requirement){
         throwIfAborted(signal);
         if(!['llama.cpp','ollama'].includes(requirement.id))return {missing:requirement};
+        // A PATH executable or HTTP listener cannot establish its compiled
+        // backend. An explicit distribution goes through its installer owner.
+        if(requirement.id==='llama.cpp'&&requirement.backend&&requirement.backend!=='auto')return {missing:requirement};
         const configuration=config[requirement.id==='llama.cpp'?'llamaCpp':'ollama']??{};
         const url=localAIServerURL(requirement.id,configuration);
         const concreteVersion=requirement.version&&requirement.version!=='latest';

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